npm package: @ifreeman666/agent-context
Description: Shared repository-native context management for Codex, Claude Code, and pi-coding-agent.
Author: ifreeman6
Latest version: 0.2.3

# @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:

```bash
npm install -D @ifreeman666/agent-context
```

Run from a project where the package is installed locally:

```bash
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`:

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

Install globally if you want a bare shell command:

```bash
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.

```bash
# 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

```text
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:

```bash
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:

```bash
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:

```md
<!-- 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

```bash
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:

```bash
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 `npm@11.5.1`, 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.