Skip to main content
The agent-context CLI manages your Agent Context System from the terminal. It initializes the file structure in a project, validates your setup, and moves proven patterns from your personal scratchpad into the shared AGENTS.md. All commands operate within your current working directory — the CLI never writes outside the project root.

​
Main commands

Sets up the Agent Context System in your current project. Run this once per clone. It is safe to re-run — it will not overwrite files that already exist.
agent-context init
What it does:
  1. Creates .agents.local.md from the bundled template (or a minimal fallback if the template is not found).
  2. Adds .agents.local.md to .gitignore, creating the file if it does not exist.
  3. Creates a CLAUDE.md symlink pointing to AGENTS.md so Claude Code picks up your context.
  4. Creates the agent_docs/ directory with starter files (conventions.md, architecture.md, gotchas.md) if AGENTS.md is present but agent_docs/ is not.
When to use it: Run init immediately after cloning a project that uses the Agent Context System, or when setting up a new project for the first time.Expected output:
Initializing Agent Context System

✓ Created .agents.local.md from template
✓ Added .agents.local.md to .gitignore
✓ Created CLAUDE.md symlink → AGENTS.md
✓ Created agent_docs/ with templates

Setup complete!

Next steps:
  1. Edit AGENTS.md with your project specifics
  2. Fill in agent_docs/ with deeper references
  3. Run 'agent-context validate' to check setup
If AGENTS.md is not present when you run init, the CLAUDE.md symlink step is skipped. Copy AGENTS.md to your project first, then re-run init.
Checks that your Agent Context System setup is correct. Use this after init and any time you want to verify nothing has drifted.
agent-context validate
What it checks:
  • AGENTS.md exists and is under 120 lines.
  • .agents.local.md exists.
  • .agents.local.md is listed in .gitignore.
  • CLAUDE.md is a symlink pointing to AGENTS.md.
  • agent_docs/ directory exists (warning if missing, not an error).
  • AGENTS.md does not contain obvious secrets (API keys, tokens, passwords).
When to use it: After initial setup, after manually editing AGENTS.md, or as part of a CI check to catch accidental secret commits.Expected output (all passing):
Validating Agent Context System

✓ AGENTS.md exists
✓ AGENTS.md is under 120 lines (87 lines)
✓ .agents.local.md exists
✓ .agents.local.md is in .gitignore
✓ CLAUDE.md symlink → AGENTS.md
✓ agent_docs/ directory exists
✓ No obvious secrets in AGENTS.md

All checks passed!
The command exits with a non-zero status if any errors are found, making it suitable for use in scripts and CI pipelines.
validate checks for common secret patterns (API keys matching sk-..., GitHub tokens matching ghp_..., and key-value patterns with words like password or token). It is not a substitute for a dedicated secrets scanner — treat it as a quick sanity check.
Shows patterns that your agent has flagged in the ## Ready to Promote section of .agents.local.md, and displays stats about how many sessions have been logged. Use this to decide what to move into AGENTS.md.
agent-context promote
What it does:Reads .agents.local.md and prints anything in the ## Ready to Promote section. Also shows the total number of sessions logged so you can judge how much history has accumulated.When to use it: Periodically — after several sessions have built up, or when your agent tells you it has flagged new patterns during compression.Expected output:
Finding Patterns to Promote

Ready to Promote (flagged by agent):

  Result<T> for error handling | src/lib/errors.ts
  DB_URL required for unit tests | set even in test env

Stats:
  Sessions logged: 8
  Use --autopromote to automatically append patterns recurring 3+ times
If no patterns have been flagged yet, it prints (none flagged yet).
Automatically appends all patterns from the ## Ready to Promote section of .agents.local.md into AGENTS.md, then clears the promoted items from the scratchpad.
agent-context promote --autopromote
What it does:
  1. Reads the ## Ready to Promote section of .agents.local.md.
  2. Checks that AGENTS.md is under 120 lines before proceeding.
  3. Appends each pipe-delimited pattern to AGENTS.md (creating a ## Patterns section if one does not exist).
  4. Clears the promoted patterns from the scratchpad and logs the promotion date.
When to use it: When you have reviewed flagged patterns with agent-context promote and are ready to commit them to AGENTS.md without manually copying each line.Expected output:
Auto-Promoting Patterns (threshold: 3 sessions)

✓ Auto-promoted 2 pattern(s) to AGENTS.md

→ Cleared promoted patterns from scratchpad
→ Review AGENTS.md and commit when ready
--autopromote writes directly to AGENTS.md. Review the result with git diff before committing. If AGENTS.md already has 120 lines, the command will refuse to run — compress or trim the file first.
You can adjust the recurrence threshold with --threshold N. The default is 3 sessions. Patterns with fewer recurrences are still shown by promote but are not auto-appended.
Prints usage information for all commands.
agent-context help
# also accepts: --help or -h

​
Helper scripts

These scripts live in scripts/ and handle memory consolidation and migration. Run them from your project root.
Checks whether automatic memory consolidation should run, based on time elapsed and session count, then triggers consolidation if the conditions are met.
./scripts/auto-consolidation-trigger.sh --check
Gates checked:
  • Time gate: At least 24 hours since the last consolidation.
  • Session gate: At least 5 sessions accumulated since last consolidation.
  • Lock gate: No consolidation already running (checked via .agents/.consolidation-lock).
When to use it: Add --check to a shell hook or run it manually when you want to let the system decide whether consolidation is warranted. Use --force when you want consolidation to run immediately regardless of thresholds.
Runs the full 4-phase memory consolidation: orient, gather, consolidate, prune. Reads recent daily logs from .agents/logs/ and merges them into the curated topic files under .agents/topics/.
./scripts/consolidate-memory.sh
What it produces:
  • Updated .agents/topics/patterns.md, .agents/topics/gotchas.md, .agents/topics/preferences.md.
  • An updated .agents/local.md index (kept under 200 lines / 25 KB).
  • Approximately a 9:1 compression ratio on accumulated session logs.
When to use it: When you want to manually trigger consolidation rather than waiting for the auto-trigger thresholds.
Migrates an older flat .agents.local.md scratchpad to the structured daily logs format (.agents/logs/YYYY-MM-DD.md and .agents/topics/).
./scripts/migrate-to-daily-logs.sh
When to use it: If you set up the Agent Context System before the daily logs format was introduced and your project still uses the legacy flat .agents.local.md file. Run once — the script exits early if it detects the migration has already happened.