- Rust 96.3%
- Nix 3.7%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
|
||
| .forgejo/workflows | ||
| docs | ||
| nix | ||
| src | ||
| tests | ||
| .editorconfig | ||
| .envrc | ||
| .gitattributes | ||
| .gitignore | ||
| AGENTS.md | ||
| Cargo.lock | ||
| Cargo.toml | ||
| CHANGELOG.md | ||
| CLAUDE.md | ||
| flake.lock | ||
| flake.nix | ||
| lefthook.yml | ||
| LICENSE | ||
| README.md | ||
quartz
quartz links a git repo to a space on a self-hosted Quartz notes server and
wires Claude Code, Codex and OpenCode into it.
quartz init signs in with Quartz's OAuth, links the repo to a space (and an
optional folder) in a committed .quartz.json, and gives each agent the
remote Quartz MCP server, a session-start hook, a per-prompt search hook, an
instructions block and a quartz skill. All of that is committed, so
teammates share it. Tokens stay per person.
Modeled on Trail-Code.
Status
Version 0.1.0, the first release. Linux and macOS.
Install
With Nix:
nix profile install git+https://git.cumsek.com/quartz/cli
nix run git+https://git.cumsek.com/quartz/cli -- init
As a flake input, with the Home Manager or NixOS module (both have the same
options: enable, package, defaultServer):
{
inputs.quartz.url = "git+https://git.cumsek.com/quartz/cli";
# Home Manager
imports = [inputs.quartz.homeManagerModules.default];
programs.quartz = {
enable = true;
defaultServer = "https://notes.example.com";
};
# NixOS: import inputs.quartz.nixosModules.default and set the same options.
}
From source (Rust 1.89 or newer):
cargo install --path .
Quickstart
cd your-repo
quartz init
init asks for the server, signs you in (a browser opens; on a machine
without one it prints a code instead), then asks for a space, a folder, the
agents and the features. It shows every file it will write before it writes
anything.
Then:
- Commit
.quartz.jsonand the agent filesinitwrote (.mcp.json,.claude/,.codex/,.agents/,opencode.json,.opencode/,CLAUDE.md,AGENTS.md). - Trust the repo in your agents: accept Claude Code's folder trust prompt,
and trust the project in Codex, then approve the quartz hooks once in
/hooks. - Sign each agent in to the Quartz MCP server (once per machine):
- Claude Code: run
/mcpand choose quartz - Codex:
codex mcp login quartz - OpenCode:
opencode mcp auth quartz
- Claude Code: run
A teammate who clones the repo runs quartz login and does steps 2 and 3.
See docs/usage.md.
Commands
| Command | What it does |
|---|---|
quartz init |
Link the repo to a space and wire the agents. Safe to re-run. |
quartz login [SERVER] |
Sign in to a server (browser, or a code with --device). |
quartz logout [SERVER] |
Revoke this device's tokens and forget them (--all for every server). |
quartz status |
Show the sign-in, the linked space and the agent wiring. No network. |
quartz doctor |
Check the whole chain and print a hint per problem. |
quartz uninstall |
Remove the agent wiring (--purge also removes .quartz.json). |
quartz spaces |
List your spaces. |
quartz ls [PATH] |
List files in the project folder. |
quartz search WORDS... |
Search the linked space (--all for every space). |
quartz read PATH |
Print a note to stdout. |
quartz new PATH |
Create a note or, with --folder, a folder. |
quartz open [PATH] |
Open the space, folder or file in the browser. |
quartz completions SHELL |
Print a shell completion script. |
Global flags: --server URL, --space SPACE, -C DIR. Every flag is in
docs/usage.md.
.quartz.json
Committed at the repo root. It holds no secret.
{
"version": 1,
"server": "https://notes.example.com",
"space": { "id": "sp_8f3a", "name": "Work" },
"folder": "projects/quartz-cli",
"agents": ["claude", "codex", "opencode"],
"features": {
"mcp": true,
"sessionContext": true,
"promptRecall": true,
"instructions": true,
"skill": true
}
}
folder is left out when the repo uses the space root.
Environment variables
| Variable | Effect |
|---|---|
QUARTZ_SERVER |
Same as --server. |
QUARTZ_SPACE |
Same as --space. |
QUARTZ_DEFAULT_SERVER |
Server to use when no flag, no .quartz.json and no earlier sign-in names one. |
QUARTZ_CONFIG_DIR |
Where credentials.json lives. Default: $XDG_CONFIG_HOME/quartz, else the platform config directory plus quartz (~/.config/quartz on Linux). |
QUARTZ_HOME |
Home directory used to detect installed agents. Meant for tests. |
BROWSER |
Command used to open URLs, instead of xdg-open or open. |
VISUAL, EDITOR |
Editor for quartz new without -m or piped input (VISUAL first, then EDITOR, then vi). |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success. |
| 1 | Any other error: server or OAuth errors, a failed doctor check, I/O. |
| 2 | Not linked to a space and no --space; or a prompt was needed and there is no terminal. Command line syntax errors also exit 2. |
| 3 | Not signed in, or the saved sign-in was revoked. |
quartz hook is the exception: it always exits 0.
Documentation
- docs/usage.md: every command, path rules, sign-in, teammates, uninstall
- docs/agents.md: what is written for each agent, the hooks, trust
- docs/architecture.md: modules, flows, token refresh, testing
- docs/development.md: build, test, CI, git flow, releasing
- CHANGELOG.md
License
AGPL-3.0-or-later. See LICENSE.