agentrecall

Keep skills, global instructions, a small permission policy, and searchable project history in one place: ~/.agents.

The CLI is agentrecall (previously dotagents). Cursor, Codex, and OpenCode already read ~/.agents; Claude Code does not, so this CLI links only where a tool cannot see it. Permissions are translated from a small YAML policy, not copied from each tool's approval history.

What syncs

Why not copy?

Copying ~/.agents/skills into every agent directory is how files go stale. On one machine, ~/.agents/skills/dev-browser was current while ~/.claude/skills/dev-browser was months old. agentrecall uses live links instead.

Skill folders are directory symlinks (POSIX cannot hardlink directories). Instruction files try a symlink first, then a hardlink with --link-mode hardlink or when a symlink cannot be created on the same volume.

Install

macOS and Linux. Python 3.11+. uv on PATH. The PyPI package is agentrecall-cli (agentrecall is taken). That install puts the agentrecall command on PATH.

uv tool install agentrecall-cli
agentrecall skills --apply
agentrecall permissions init --apply
agentrecall permissions --apply

That puts agentrecall on PATH, links the bundled search-project-history skill into ~/.agents/skills (and into Claude Code), and grants ~/.agents/history to Claude, Codex, and OpenCode so the search index can update. Cursor, Codex, and OpenCode already read ~/.agents/skills.

One-off without installing: uvx --from agentrecall-cli agentrecall status. From unreleased main: uv tool install git+https://github.com/bluearpit/agentrecall.git.

Then, in a project, build the index once:

agentrecall history reindex --cwd .

The CLI checks GitHub at most once a day and prints a notice when a newer release exists. It does not upgrade by itself. agentrecall upgrade is dry-run; agentrecall upgrade --apply installs that version from PyPI. Agents should ask before applying.

From a checkout:

uv tool install -e .
# or, for development:
uv sync --group dev
uv run agentrecall status

Commands

Write commands are dry-run unless --apply.

agentrecall status
agentrecall upgrade             # dry-run
agentrecall upgrade --apply     # install that version from PyPI
agentrecall skills              # dry-run
agentrecall skills --apply      # link ~/.agents/skills into Claude Code
agentrecall skills --apply adopt
agentrecall instructions --apply
agentrecall project --apply     # CLAUDE.md -> @AGENTS.md
agentrecall history reindex --cwd .
agentrecall history search "the decision about X" --cwd .
agentrecall history search "the decision about X" --cwd ~/work/other-app
agentrecall history search "the decision about X" --all
agentrecall history search "the decision about X" --cwd . --sort recent
agentrecall history show ~/.claude/projects/.../sess.jsonl --grep "the decision"
agentrecall history list --cwd .
agentrecall history list --cwd . --since 2026-08-01
agentrecall history commands --cwd .
agentrecall history commands --cwd . --kind test
agentrecall permissions init --apply
agentrecall permissions                 # dry-run mapping
agentrecall permissions --apply         # user ~/.agents/permissions.yaml -> user agent files
agentrecall permissions init --cwd . --apply
agentrecall permissions --cwd . --apply # project .agents/permissions.yaml -> project files

--link-mode auto|symlink|hardlink applies to files. Skill folders always symlink.

Layout

~/.agents/
  AGENTS.md                 # global instructions (source of truth)
  skills/<name>/SKILL.md    # user skills
  permissions.yaml          # portable allow/deny policy
  history/index.sqlite      # search index only; not full transcripts

CLAUDE_CONFIG_DIR, CODEX_HOME, and XDG_CONFIG_HOME are honored.

History is keyed by project directory (and git root when present). Search, list, and commands default to the current project (--cwd .). Pass --cwd /path/to/project for one other repo, or --all for every indexed project. It is not stored in the git repo. Do not commit ~/.agents/history/. Searching chats is not the same as resuming a Claude session inside Cursor.

The bundled skill search-project-history is installed into ~/.agents/skills on agentrecall skills --apply, then linked into Claude Code like any other skill. Agents should run agentrecall history search "<query>" --cwd . to triage the current repo (or --cwd <path> / --all when the question is not about this repo), then agentrecall history show <source_path> --grep "<term>" to verify, instead of scraping transcript files themselves.

Permissions

Write a small policy, not a dump of every command you ever approved:

allow_shell:
  - git status
  - git diff
  - agentrecall
deny_shell:
  - git push --force
allow_fetch:
  - github.com
workspace_write: true
external_write:
  - ~/.agents/history

agentrecall permissions --apply turns that into:

The default policy allowlists agentrecall and grants ~/.agents/history so history search can update the index without a one-off sandbox prompt. Add more paths under external_write if you also want ~/.agents/skills writable.

Existing unrelated allow rules are kept. Previously generated agentrecall rules are replaced on the next apply (tracked in permissions.managed.json, not for git).

Not translated: MCP ids (mcp__plugin_...), one-off heredoc approvals, bypassPermissions / run-everything modes, Cursor's sandbox prompt for writes outside the project, or full Seatbelt/Bubblewrap profiles.

See examples/permissions.yaml.

Development

See CONTRIBUTING.md for setup, checks, and how PRs merge.

uv sync --group dev
uv run ruff check src tests
uv run ruff format --check src tests
uv run pytest

CI runs the same lint and tests on Python 3.11–3.13, then builds and smoke-tests the wheel and source distribution. The ci job is the merge gate: it is green only when every check passes. Tests always set HOME to a temporary directory.

A published GitHub release also uploads to PyPI as agentrecall-cli. The workflow uses Trusted Publishing (no API token). GitHub environment pypi; workflow publish.yml.

Related tools

• npx skills — install skills from GitHub into agent directories
• cc_transcript_viewer — GUI for the same local JSONL files

License

MIT