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 init

For faster hooks, install it globally:

$ npm install -g @agentreel/agent$ agentreel init

init 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

  1. Sign in with your email. You get a one-time link.
  2. In Settings, generate an API key. It is shown once.
  3. Link the agent and start the uploader:
$ agentreel link <your-key> --api https://api.agentreel.dev$ agentreel daemon --detach

Without 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 watch

Secrets 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/$ *.pem

Other 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.

Sharing replays

Every uploaded session has a private, unlisted link. Open it from the dashboard and copy it from the replay header.

Share settings set an expiry of 7, 30 or 90 days, or none. Password-protected links are a Pro feature. Free sessions are kept for 7 days.

Uninstall

$ agentreel uninstall$ npm uninstall -g @agentreel/agent

uninstall 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).