Docs@agentreel/agent 0.2.0
Docs
The local agent records Claude Code and Cursor sessions on your machine. You choose when to upload and share them. These docs cover @agentreel/agent 0.2.0.
What it captures
- Prompts you send to the agent.
- Shell commands with output, exit code and duration.
- File reads and edits, with the diff.
- Tool and MCP calls, with input and result.
- Who and where: OS user, hostname, git user, repo remote (credentials stripped), branch and commit at start and end, agent and AgentReel versions.
- Token counts and cost when the agent reports them.
Everything goes to a local SQLite buffer at ~/.agentreel/sessions.db first. It works offline. Nothing uploads until you connect an account.
Install
Needs Node 20 or newer, on macOS, Linux or Windows (WSL recommended).
$ npx @agentreel/agent initFor faster hooks, install it globally:
$ npm install -g @agentreel/agent$ agentreel initinit creates ~/.agentreel/sessions.db and ~/.agentreel/config.json and installs the hooks for both tools. Skip one with --no-claude or --no-cursor.
Connect your account
- Sign in with your email. You get a one-time link.
- In Settings, generate an API key. It is shown once.
- Link the agent and start the uploader:
$ agentreel link <your-key> --api https://api.agentreel.dev$ agentreel daemon --detachWithout the daemon, upload by hand with agentreel push. agentreel status shows what is still queued.
Claude Code
init adds hooks to ~/.claude/settings.json for the session lifecycle events, including SessionStart, UserPromptSubmit, PreToolUse, PostToolUse and SessionEnd. Each hook runs agentreel hook <Event>. A backup of the previous file is kept.
Open Claude Code as usual. The next session is recorded.
Cursor
init adds observe-only hooks to ~/.cursor/hooks.json: sessionStart, sessionEnd, beforeSubmitPrompt, postToolUse, postToolUseFailure, afterShellExecution, afterMCPExecution, afterFileEdit, subagentStop and stop. They cannot approve or block anything.
To also record edits you make by hand, run the optional watcher:
$ agentreel watchSecrets and .agentreelignore
Scrubbing runs on your machine before anything is saved. It removes private keys, credentials in URLs, auth headers, passwords, JWTs, AWS, GitHub, OpenAI, Anthropic, Stripe, Slack, Google and npm tokens, dotenv secrets, emails and IPv4 addresses. Diffs are computed from the scrubbed text.
Add a .agentreelignore to a project, in gitignore syntax. Events on matching files stay on the timeline, but their contents, edits and tool output are dropped.
# .agentreelignore$ .env*$ secrets/$ *.pemOther controls: agentreel pause and resume, agentreel forget to delete local sessions, agentreel config hostname hash (or omit), and agentreel config attribution off.
AgentReel Guard
AgentReel Guard flags risky agent behavior, such as destructive filesystem commands, commands aimed at production databases, secret exfiltration and prompt injection. The patterns are based on publicly documented incidents. See the detection catalogue and the security page.
Detection runs on your machine, not on AgentReel servers. The guard is on by default. Findings are not stored locally. The agent works them out from the recorded session when you run agentreel scan, and again when a session is uploaded. The scan is local and makes no network calls.
$ agentreel scan$ agentreel scan <session-id>agentreel scan [session-id] scans a session for risky agent behavior patterns. Leave the session id out to scan the most recent session.
When the background uploader (agentreel daemon) or agentreel push uploads a session, it sends that session's findings with it: the rule id, severity, category, time and an evidence excerpt of up to 500 characters, with detected secrets redacted first. Redaction is automatic and may not catch every secret or personal detail. Evidence can include command text, file paths and hostnames. The agent includes guard findings in uploads. Our servers currently discard them and do not store them. If we start storing them, we will update our Privacy page first.
Detection is observe-only. It flags risks but does not block commands. To stop findings being worked out or sent, set "enabled": false in ~/.agentreel/guard-config.json. This does not stop sessions from being uploaded.
Uninstall
$ agentreel uninstall$ npm uninstall -g @agentreel/agentuninstall stops the uploader and removes the hooks from both config files, keeping a backup. Local data stays in ~/.agentreel until you delete that folder.
CLI reference
agentreel init- Install the Claude Code and Cursor hooks and create the local buffer. --no-claude or --no-cursor skips one.
agentreel status- Local capture status, recent sessions and the upload queue.
agentreel scan [session-id]- Scan a session for risky agent behavior patterns. Local, no network calls. Leave the id out to scan the most recent session.
agentreel link [api-key]- Connect to your account. Prompts for the key if you leave it out. --api <url> sets the server (default https://api.agentreel.dev).
agentreel push- Upload pending events now. --retry-held retries sessions the server refused for the plan limit.
agentreel daemon- Run the background uploader (30s ticks, 1MB early flush, exponential backoff). --detach runs it in the background and logs to ~/.agentreel/daemon.log.
agentreel stop- Stop the background uploader.
agentreel pause- Pause capture. Hooks and the watcher do nothing until resume.
agentreel resume- Resume capture.
agentreel forget [session-ids...]- Delete sessions from the local buffer. --all wipes everything (asks first), --force skips the prompt.
agentreel watch- Optional Cursor history watcher. Turns saved snapshots into diffs for manual edits.
agentreel config [key] [value]- Show or change settings: hostname plain|hash|omit, attribution on|off.
agentreel logout- Clear the local credentials.
agentreel uninstall- Remove the AgentReel hooks from ~/.claude/settings.json and ~/.cursor/hooks.json.
Open source and licensing
The @agentreel/agent local agent is open source on GitHub. Starting with version 0.2.1 it is under the Apache License 2.0 (SPDX Apache-2.0). Versions 0.2.0 and earlier are under the MIT License.
The production tracking backend (this website, ingest API, dashboard, and replay hosting) stays closed source and hosted. If its source is ever published it will be under the Functional Source License (FSL).