No description
  • Rust 96.3%
  • Nix 3.7%
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
marti 6cdc83b32c
Some checks failed
release / release (push) Failing after 10s
ci / check (push) Successful in 1m40s
Merge branch 'develop' into main for 0.1.0
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 12:37:22 +01:00
.forgejo/workflows ci: add the forgejo check and release workflows 2026-11-16 12:29:59 +01:00
docs fix(init): keep the mcp choice when the server has no MCP endpoint 2026-11-16 12:35:15 +01:00
nix fix(init): keep the mcp choice when the server has no MCP endpoint 2026-11-16 12:35:15 +01:00
src fix(init): keep the mcp choice when the server has no MCP endpoint 2026-11-16 12:35:15 +01:00
tests test(init): link, rerun, status, doctor and uninstall a repo end to end 2026-11-16 12:28:16 +01:00
.editorconfig chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
.envrc chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
.gitattributes chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
.gitignore chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
AGENTS.md docs: add AGENTS.md for coding agents and link CLAUDE.md to it 2026-11-16 12:34:19 +01:00
Cargo.lock chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
Cargo.toml feat(credentials): load, save and lock the credential store 2026-11-16 12:18:48 +01:00
CHANGELOG.md docs: add the changelog with the 0.1.0 entry 2026-11-16 12:34:19 +01:00
CLAUDE.md docs: add AGENTS.md for coding agents and link CLAUDE.md to it 2026-11-16 12:34:19 +01:00
flake.lock chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
flake.nix build(nix): add the overlay, home manager and nixos modules and flake checks 2026-11-16 12:29:59 +01:00
lefthook.yml ci: add a lefthook pre-commit for rust and nix formatting 2026-11-16 12:29:59 +01:00
LICENSE chore: scaffold the quartz cli crate, flake and module interfaces 2026-11-16 12:14:20 +01:00
README.md docs: add the readme 2026-11-16 12:31:43 +01:00

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:

  1. Commit .quartz.json and the agent files init wrote (.mcp.json, .claude/, .codex/, .agents/, opencode.json, .opencode/, CLAUDE.md, AGENTS.md).
  2. 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.
  3. Sign each agent in to the Quartz MCP server (once per machine):
    • Claude Code: run /mcp and choose quartz
    • Codex: codex mcp login quartz
    • OpenCode: opencode mcp auth quartz

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

License

AGPL-3.0-or-later. See LICENSE.