@ifreeman666/agent-context

@ifreeman666/agent-context is a publishable Node.js/TypeScript CLI for sharing repository-native project context across Codex, Claude Code, and pi-coding-agent.

It does not try to synchronize chat transcripts. Instead, it keeps durable project and task context inside repository files and regenerates each agent's entrypoints from a single config file.

It also avoids clobbering existing entrypoint files unnecessarily. Managed blocks live under .agent-context/snippets/. For existing root AGENTS.md and CLAUDE.md files without markers, agent-context appends the managed block to the end of the file. Other existing entrypoints still stay in manual mode unless they already contain agent-context markers.

Why

Long conversational state does not compose well across multiple coding agents. The stable approach is:

• keep durable context in versioned files
• keep dynamic task state in task folders
• regenerate thin agent-specific adapters
• use git worktrees for concurrent implementation

Install

Local dev dependency:

npm install -D @ifreeman666/agent-context

Run from a project where the package is installed locally:

npx agent-context init --task TASK-001
# or
npm exec agent-context init -- --task TASK-001
# or
./node_modules/.bin/agent-context init --task TASK-001

Run without adding it to devDependencies:

npx @ifreeman666/agent-context init --task TASK-001

Install globally if you want a bare shell command:

npm install -g @ifreeman666/agent-context
agent-context init --task TASK-001

Common Commands

Most commands work without --repo . when you run them inside the repository. Most commands also work without --task after a current task has been set.

# 1. Initialize once
npx agent-context init --task TASK-001

# 2. Or let agent-context generate a readable task ID from a description
npx agent-context init --task "add repair command"

# 3. Switch or create the active task
npx agent-context sync --task TASK-002

# 4. Preview the shared context for the active task
npx agent-context bootstrap

# 5. Append durable progress for the active task
npx agent-context handoff --agent codex --file handoff.md

# 6. Repair shared context files and the active task scaffold
npx agent-context repair

# 7. Remove agent-context files and managed wiring
npx agent-context remove

# 8. Check whether Codex / Claude / pi entrypoints are wired
npx agent-context doctor

# 9. Validate generated files and task structure
npx agent-context validate

When Flags Are Needed

• --repo <path>: only needed when you run the command outside the target repository.
• --task <TASK_ID>:
  • useful on init to create the first task
  • useful on sync to switch the active task
  • on init, sync, and repair, you can also pass a natural-language description such as "add repair command" and agent-context will generate a readable task ID like TASK-001-add-repair-command
  • optional on bootstrap, handoff, and validate if docs/agent-context/current-task.txt is already set

What sync Does

sync regenerates the agent entrypoints from agent-context.config.json.

With --task, it also creates or activates that task by updating docs/agent-context/current-task.txt.

What repair Does

repair restores repository-level context files, regenerates agent entrypoints, and recreates any missing files for the active task.

With --task, it can also switch to or create a task from either an explicit ID or a natural-language description.

What remove Does

remove fully uninstalls agent-context from the repository.

It removes:

• agent-context.config.json
• .agent-context/
• docs/agent-context/
• fully managed entrypoint files such as generated .claude/agents/* and .pi/extensions/repo-context.ts

For mixed files such as existing AGENTS.md or CLAUDE.md, it removes only the managed marker block and preserves the rest of the file.

Generated Structure

agent-context.config.json
.agent-context/
  snippets/
    AGENTS.md
    CLAUDE.md
    claude-implementer.md
    claude-reviewer.md
    repo-context.ts
  state.json
AGENTS.md
CLAUDE.md
.claude/agents/
  implementer.md
  reviewer.md
.pi/extensions/
  repo-context.ts
docs/agent-context/
  bootstrap.md
  project.md
  architecture.md
  conventions.md
  decisions.md
  current-task.txt
  tasks/
    README.md
    TASK-001/
      brief.md
      handoff.md
      status.json
      verification.md

Workflow

Typical day-to-day usage:

1. Run init once per repository.
2. Use sync --task TASK-xxx when you want to create or switch the active task.
3. Let agents read and write durable state under docs/agent-context/.
4. Use doctor when wiring looks wrong, repair when files drift, and validate before handoff or merge.

EntryPoint Strategy

agent-context manages entrypoints with a non-destructive strategy:

• If AGENTS.md, CLAUDE.md, .claude/agents/*.md, or .pi/extensions/repo-context.ts do not exist, it creates them with managed marker blocks.
• If a file already contains the matching agent-context marker block, sync updates only that block.
• If AGENTS.md or CLAUDE.md already exist without markers, sync preserves the existing content and appends the managed block to the end.
• If other entrypoint files already exist without markers, sync preserves them and writes a ready-to-paste snippet under .agent-context/snippets/.

This means existing project instructions are not overwritten by default.

Adapter Notes

• Codex: gets a generated AGENTS.md that points to the shared context files.
• Claude Code: gets CLAUDE.md plus two subagent role files under .claude/agents/.
• pi-coding-agent: gets a TypeScript extension that exposes an agent_context_bootstrap tool and a context command. The current task is read from docs/agent-context/current-task.txt.

The Pi adapter is intentionally conservative. It surfaces the shared bootstrap through a tool and command instead of assuming undocumented prompt injection hooks.

Troubleshooting

If you installed the package with npm install -D @ifreeman666/agent-context and agent-context is not found in your shell, that is expected npm behavior. Local package binaries are linked into ./node_modules/.bin, not added to your shell's global PATH. Use one of:

npx agent-context init
npm exec agent-context init
./node_modules/.bin/agent-context init

If you want agent-context to work as a bare command in any shell, install it globally:

npm install -g @ifreeman666/agent-context

If doctor reports manual for entrypoints such as .claude/agents/*.md or .pi/extensions/repo-context.ts, insert the matching snippet file from .agent-context/snippets/ into the existing file. The easiest durable form is to paste the entire block including:

<!-- agent-context:codex:start -->
...
<!-- agent-context:codex:end -->

or the Claude equivalent. Once the marker block exists, future sync runs update only the managed section.

Development

npm install
npm run typecheck
npm run test
npm run build

Release

This repository publishes automatically when you push a version tag that matches package.json.

Release flow:

npm version patch
git push --follow-tags

The publish workflow expects:

• a tag shaped like v0.1.1
• package.json version to equal the tag without the v
• npm trusted publishing configured for repository ifreeman6/agent-context
• workflow filename publish.yml registered in npm's Trusted Publisher settings

The publish job uses GitHub Actions OIDC with npm trusted publishing, installs [email protected], and publishes to the public npm registry.

This repository is currently private, so the workflow does not request npm provenance. npm only accepts provenance for supported public source repositories.