AgentRecord 🗃️

Local-first, evidence-backed professional AI work profiles from local agent traces.

简体中文 | English

---

📌 What is AgentRecord?

AgentRecord turns local AI-agent work traces into a user-owned, auditable, and privacy-safe AI work profile.

It is not a hiring score, a competitive leaderboard, an arbitrary certification, or a raw prompt-history viewer. The first product surface is a personal AI work record: it maps what kinds of work you do with agents, how you delegate, how you review, how you verify, and what evidence supports those claims.

---

🖼 Preview

Generated locally from redacted aggregate signals. Raw conversations, private paths, and secrets are not included in the public artifact.

---

🚀 Quickstart

Get up and running locally in under 2 minutes.

🤖 Agent-Native Quickstart (Let Your Agent Do the Work!)

Since you are using an AI agent right now (such as Claude Code, opencode, Codex, etc.), you can ask it to run one command:

You are an AI assistant with terminal command execution. Please generate my local AgentRecord work profile.

Run this command:
`npx -y @iiwish/agentrecord@latest generate --open`

Do not upload raw conversations, code, secrets, or local trace files. When finished, tell me whether validation passed and where the generated `index.html` file is.

Optional: if I provide a display name, add `--display-name "<name>"` to the command. If Codex account usage is unavailable or I want a local-log-only run, add `--no-account-usage`.

Manual CLI Quickstart

1. Generate Your Profile

npx -y @iiwish/agentrecord@latest generate --open

This initializes local config if needed, builds the profile, validates privacy/schema boundaries, reads Codex account usage when available, and opens the generated HTML report.

For a local-log-only or offline run, add --no-account-usage.

(Or install globally with npm install -g @iiwish/agentrecord and run agentrecord generate --open.)

2. Advanced: Initialize Config

agentrecord init --owner <owner_id> --display-name "Your Name"

This generates a baseline agentrecord.config.json containing output destinations, privacy options, and adapter setups.

3. Advanced: Scan & Build

# Scan for local agent data sources
agentrecord scan --config ./agentrecord.config.json

# Build your public-safe profile artifacts
agentrecord build --config ./agentrecord.config.json --no-account-usage

4. Advanced: Validate & Open

# Verify integrity, schema structure, and privacy boundaries
agentrecord validate --config ./agentrecord.config.json

# Launch the human-readable passport report in your default browser
agentrecord open --config ./agentrecord.config.json

---

⚖️ The Shift: AI-Native Developer Identity

In a software world where AI agents generate a massive portion of pure code lines, the developer's core value is undergoing a fundamental paradigm shift. Your professional excellence is no longer measured solely by keystroke count, but by high-order orchestrational abilities:

1. Goal Framing & Context Packaging: How cleanly you articulate complex requirements and supply context to an agent.
2. Agent Delegation & Coordination: How effectively you break down hairy problems and orchestrate multiple specialized agents.
3. Review Judgment & Verification: How rigorously you check agent output, enforce safety constraints, and catch silent hallucinations.
4. Failure Recovery & Resilience: How gracefully you recover from agent errors, trace failures, and iteratively pivot.

AgentRecord is the local record layer for proving these AI-native engineering strengths.

---

🧩 How It Works

AgentRecord compiles and normalizes your private agent sessions (Codex, opencode, Claude Code, etc.) using a deterministic evidence engine. Your raw conversations, codebases, and secrets never leave your machine.

 ┌───────────────┐   ┌───────────────┐   ┌───────────────┐
 │ Codex Session │   │ opencode DB   │   │ Claude Code   │  (Supported Adapters)
 └───────┬───────┘   └───────┬───────┘   └───────┬───────┘
         │                   │                   │
         └───────────┬───────┴───────────────────┘
                     ▼
         ┌───────────────────────────┐
         │     Event Normalizer      │  (Client-neutral event modeling)
         └───────────┬───────────────┘
                     ▼
         ┌───────────────────────────┐
         │      Evidence Engine      │  (Deterministic aggregate matching)
         └───────────┬───────────────┘
                     ▼
         ┌───────────────────────────┐
         │       Profile Model       │  (Ability scoring & role profiling)
         └───────────┬───────────────┘
                     ▼
   ┌─────────────────┴─────────────────┐
   ▼                                   ▼
 ┌───────────────────────────┐       ┌───────────────────────────┐
 │    index.html Passport    │       │     profile.json/md       │  (Human- & Machine-
 │   (Zero-JS Static Page)   │       │   (Compact Agent Pack)    │   readable artifacts)
 └───────────────────────────┘       └───────────────────────────┘

---

✨ Key Features

• 🔒 Privacy-by-Design (Zero-Leakage)
  • All original prompt texts, raw responses, attachments, terminal logs, absolute private paths, and secrets stay safely hidden. Artifacts only contain public-safe aggregated statistics and redacted evidence cards.
• 🔬 Evidence Over Claims (Auditability)
  • No inflated arbitrary ranks. Every single claim, role signal, or competency dimension points back to verified local evidence cards (evidence.jsonl).
• 🔄 Cross-Agent Normalization
  • Uses pluggable local adapters that process and normalize different agent traces (Codex session directories, opencode SQLite databases, Claude Code project traces) into a stable, unified model.
• ⚡ Incremental & Deterministic
  • Processes updates incrementally using private local cursors without rebuilding the history. Built on deterministic algorithms—no LLM dependency required for core profile synthesis.
• 🤖 Prompt-Ready Agent Context
  • Generates a compact context pack (agent-context.md and agent-context.json) that future agents can read in milliseconds to understand your workflows, preferences, and collaboration style.

---

🛠️ CLI Commands & Overrides

Command	Description	Key Overrides / Examples
generate	Initializes config if needed, builds, validates, and optionally opens the HTML profile.	--open --config <file> --owner <id> --display-name "Name" [--no-account-usage]
init	Initializes the local configuration schema.	--dry-run --owner <id> --display-name "Name" --profiles-dir <dir> --output <dir>
scan	Detects supported agent tools and local databases.	--config <file> --sessions-dir <dir> --opencode-db <file> --claude-code-projects-dir <dir>
build	Generates structured JSON, MD, and HTML profiles.	--config <file> --owner <id> --locale zh-CN --display-name "Name" --agent-context --no-account-usage --account-usage-timeout-ms <ms> --sessions-dir <dir> --opencode-db <file> --opencode-data-dir <dir> --no-opencode --claude-code-projects-dir <dir> --no-claude-code
validate	Validates privacy, schemas, and locale completeness.	--config ./agentrecord.config.json
open	Opens the output HTML report safely in your browser.	--config <file> --owner <owner>
doctor	Checks environment, Node version, and database access.	agentrecord doctor

---

📂 Expected Artifact Outputs

All generated profile outputs default to profiles/<owner>/:

profiles/<owner>/
├── profile.json           # Machine-readable unified AI work profile
├── evidence.jsonl         # Redacted evidence cards mapping actions to confidence
├── index.html             # The Interactive AI Work Passport (single-file, zero-JS, static)
├── profile.md             # Secondary human-readable markdown summary
├── redaction-report.md    # Local privacy boundary audit logs
├── run-report.md          # Incremental compilation summary
└── .agentrecord/          # Private cursor snapshots, timestamps, and cache (DO NOT SHARE)

🎯 Optional Opt-In Outputs

By passing the --agent-context flag during build, you can export a highly condensed profile pack designed for direct LLM context windows:

• agent-context.md: Human-legible developer-style guide for new agents.
• agent-context.json: Compact JSON representation of your operating constraints.

---

🔌 Supported Local Adapters

Adapter	Source Path	Collected Metadata	Privacy Guarantee
Codex	Local session rollouts	High-level trace aggregations & account token activity.	Excludes raw system prompts, content attachments.
Claude Code	~/.claude/projects	Project count, trace session timestamps, token totals.	Excludes raw prompts, diff fragments, and CLI logs.
opencode	~/.local/share/opencode/opencode.db	Session metadata, trace windows, activity cost, token metrics.	Reads SQLite DB metrics; completely ignores tool output.

---

🛣️ Roadmap & Milestones

The journey to making AgentRecord the gold standard for AI-native engineering profiles:

• Milestone 0: Repository Foundation - Clean CLI package architecture, localization parity, and MIT release metadata.
• Milestone 1: Local CLI Baseline - init / scan / build / validate / open, Codex local traces, privacy validation, and incremental state.
• Milestone 2: Shareable Proof Page - Single-file index.html AI work passport with screenshot-ready share cards and editable display name.
• Milestone 3a: Active Local Adapters - Codex, opencode, and Claude Code aggregate metadata adapters.
• Milestone 3b: Additional Adapters - OpenClaw, Hermes, and deeper adapter capability reporting.
• Milestone 4a: Agent Context Pack - Optional --agent-context exports for future agent handoff.

For full specifications, read ROADMAP.md.

---

🤝 Contributing

AgentRecord is open-source and welcomes contributions! To work with the code locally:

# Clone the repository
git clone https://github.com/iiwish/agentrecord.git
cd agentrecord

# Perform validation checks
npm run check

# Perform dry-run package packing
npm run pack:dry

# Run smoke tests
npm run smoke:install
npm run smoke:share-card
npm run smoke:card-diversity

Before contributing, please read the Docs Architecture and Privacy and Trust Specifications.

---

📄 License

AgentRecord is licensed under the MIT License.