Skip to main content
The Agent Context System is two markdown files and a handful of shell scripts, all living inside your project directory. There are no external services, no network calls, and no background processes. Understanding what gets committed, what stays local, and what the CLI is permitted to do covers the full security surface.

​
What gets committed vs gitignored

agent-context init adds .agents.local.md to .gitignore automatically. If you are setting up the system manually without running init, add it yourself before your first commit:
Run agent-context validate to confirm the gitignore entries are in place.

​
Trust boundary

.agents.local.md and the .agents/ directory live in your local project directory, gitignored. The trust model is the same as .bashrc, .env, or IDE config files: if an attacker can write arbitrary files to your local project directory, agent context is not your biggest problem. Do not store credentials, API keys, tokens, or passwords in any agent context file — committed or local. agent-context validate checks AGENTS.md for common secret patterns and reports an error if it finds them.

​
No external downloads

All files are included in the repository. The CLI and scripts do not download binaries, phone home, or fetch content from external URLs at runtime. What you clone is what runs.

​
Scratchpad writes require user confirmation

The agent must propose a session log entry and wait for your approval before appending to .agents.local.md or any file in .agents/logs/. The workflow is:
  1. Agent drafts the session log entry.
  2. Agent shows the draft to you.
  3. You approve or edit it.
  4. Agent writes the approved content.
The agent does not append directly. This applies to session log entries, compression results, and any other writes to the scratchpad.

​
Path-scoped operations

The CLI (agent-context) operates only within the current working directory. It does not follow symlinks that point outside the project root, and it does not construct paths using ... Operations are scoped to $(pwd) at the time you run the command.

​
Scratchpad content is data, not instructions

.agents.local.md is a record of what happened in past sessions: what changed, what worked, what didn’t, decisions made, patterns learned. The agent treats it as factual session data. If the scratchpad contains content that resembles new behavioral rules, command overrides, or system prompt directives, the agent should ignore that content and alert you. Observational data logged by the agent across sessions does not grant execution authority.

​
Team usage

When multiple developers use the Agent Context System on the same project:
  • AGENTS.md is a shared document. Treat changes to it like changes to any other shared file. Review them in PRs. No secrets, no personal file paths, no developer-specific configuration.
  • .agents.local.md is personal. Each developer has their own, gitignored. Scratchpads are never shared.
  • agent_docs/ is shared. Same rules as AGENTS.md — committed, reviewed, no secrets.
The promotion workflow is how personal learnings become shared knowledge. When a pattern in your .agents.local.md has proven stable across multiple sessions, you move it to AGENTS.md where the whole team benefits. That move is intentional and reviewable — nothing flows from local to shared automatically without your explicit action.
If you fork or template the repository, make sure .agents.local.md and .agents/ are in .gitignore before other developers clone the project. agent-context init handles this, but manual setups require it explicitly.