Kris Yotamname AGENTS.md and SOUL.md as the one-line recognition files7c7b8df2 months agoHistory
NameLast commit messageLast commit date
..
hosts.md
log.csv
models.env.example
models.md
README.md
subagents.md
README.md

model/

Shared primitives for every agent CLI on this machine. Plain files, no tooling. Any agent reads what it needs from here instead of asking again.

Config lives in $XDG_CONFIG_HOME/model/ (default ~/.config/model/). The session log lives in $XDG_STATE_HOME/model/log.csv (default ~/.local/state/model/log.csv). Each agent's AGENTS.md or SOUL.md (or CLAUDE.md, GEMINI.md) gets exactly one line pointing here. That line is how the agent finds this directory. Nothing else duplicates this content.

Files

File What
hosts.md Every machine: IPs, SSH, sudo, what runs there
subagents.md How to invoke any other agent CLI headlessly
models.env Shared env, sectioned per agent. chmod 600.
models.md Slug index. One canonical id per model, every vendor.
~/.local/state/model/log.csv Session log. Every agent appends one row when a session ends.

Model slugs

Every model has one slug, listed in models.md, formed as <vendor-prefix>-<vendor's own model id>: lowercase, hyphens, no spaces. claude-fable-5, cursor-composer-2.5, openai-gpt-5-6-sol, deepseek-v4.

Using a model that is not in models.md? Mint its slug and add the row on first use, before writing the log row. Never invent a second slug for a model that already has one, and never retire a row. Old log rows still point at it.

Session log

Append one row to ~/.local/state/model/log.csv at the end of a session:

date,company,model,effort,description,prompt,resume
2026-07-28,anthropic,claude-fable-5,high,ported the model standard to src,,claude --resume 9cbb2d13-ef46-...
  • date: YYYY-MM-DD.
  • company: provider, lowercase: anthropic, openai, cursor, xai, moonshot, zhipu, deepseek.
  • model: the slug from models.md. Not the marketing name.
  • effort: reasoning effort actually used: none, low, medium, high, xhigh, max. none if the model has no such setting.
  • description: one line, what the session did.
  • prompt: path to the artifact in ~/.prompt/, e.g. ~/.prompt/loop/pr-triage.html. Empty for an ad-hoc session.
  • resume: the full command to resume it, or the bare session id if the CLI has no resume.

Quote any field containing a comma. One table, so grep -i ',anthropic,' or awk -F, '$3=="claude-fable-5"' filters it.

Rules

  • Facts live here once. If you find a fact duplicated in an agent's system file, move it here and leave the pointer line.
  • models.env holds no secrets in version control. Real values come from the secret manager.
  • Documentation lives in the docs repo synced at <PATH>, not here. Reference it by path.
  • Adding a primitive: new <topic>.md, one row in the table above. Do not add a loader, a schema, or a config format.
  • log.csv is state. Do not put it back in this directory.