Agent Toolchain

A self-contained toolchain for AI-agent sessions lives in scripts/ and .model/. It is deployed as out-of-store symlinks in ~/.local/bin via home/scripts.nix, so the three commands are available in every project, not just this repo.

flowchart LR
    SS["agent CLI session"] --> AS["agent-scaffold"]
    AS --> M[".model/<br/>CLAUDE · AGENTS · GEMINI.md"]
    AS --> MEM[".memory/ (memd init)"]
    MEM --> CUR["memd curator<br/>distills transcripts"]
    CUR --> FILES["state · decisions · mistakes · todo .md"]
    CLAUDE["Claude (orchestrator)"] -->|brief| TETHER["tether"]
    TETHER -->|agy| GEM["Gemini (worker)"]
    GEM -->|RESULT / EVIDENCE / BLOCKERS| CLAUDE

memd — project-memory curator

memd (scripts/memd/) autonomously distills AI session transcripts into a project's .memory/ files. It is packaged as a Nix derivation and also symlinked live for editing.

File	Holds
.memory/state.md	Live status, configs, ports, active workarounds
.memory/decisions.md	Canonical architecture decisions
.memory/mistakes.md	Append-only audit log of bugs/issues
.memory/todo.md	Open tasks
.memory/inbox/	Write interface — drop dated notes for the curator

• Read the memory files at session start. Write only by dropping a markdown note in .memory/inbox/; the next sweep ingests and deletes it.
• A memd-sweep systemd user timer (~30 min, home/scripts.nix) catches up stale projects, ingests inboxes, prunes oversized files, and detects new git repos — independent of any session.
• Session hooks (SessionStart, SessionEnd, PreCompact) wire memd into Claude Code.

Never hand-edit .memory/

The curator maintains invariants (frontmatter, append-only mistakes.md, size budgets, per-project locks, apply-then-advance cursors). Manual edits race the background runs. Scaffold with memd init, never by hand.

tether — Claude → Gemini delegation

tether (scripts/agent-tether/, contract mirrored under .model/agent-tether/) lets Claude (the orchestrator) hand scoped task briefs to Gemini (the worker) via agy. The worker executes literally and reports in a RESULT / EVIDENCE / BLOCKERS format.

tether run [-m pro|pro-low|flash|flash-high|flash-low] [-d DIR] [-t TASK] [-y] "BRIEF"
tether continue TASK "FOLLOW-UP"
tether status [TASK] | log [N] | models

• Default workdir is $PWD; paths under ~/.nix-config auto-map to the non-hidden ~/volnix alias (the Antigravity CLI rejects hidden workspace paths).
• The full contract is in .model/agent-tether/PROTOCOL.md.

Never delegate

Architecture decisions, .memory/ curation, destructive/system operations, and final user-facing answers stay with the orchestrator.

agent-scaffold — project bootstrap

agent-scaffold (scripts/agent-scaffold/) is a Fish script that, at any git root, idempotently renders .model/{CLAUDE,AGENTS,GEMINI}.md from a single template and runs memd init when .memory/ is absent. It runs on Claude Code SessionStart and via the agy Fish wrapper before Antigravity launches — deliberately not a cd/$PWD hook, so merely entering a third-party repo never litters it with scaffolding.

This documentation site itself was produced with this toolchain — the Desktop section was drafted by Gemini through tether.