# AgentRecord ๐๏ธ
**Local-first, evidence-backed professional AI work profiles from local agent traces.**
[](https://www.npmjs.com/package/@iiwish/agentrecord)
[](LICENSE)
[](package.json)
[](#privacy-and-trust-by-design)
[](#status)
[็ฎไฝไธญๆ](./README.zh-CN.md) | [English](./README.md)
---
## ๐ 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.
---
## ๐ 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:
```text
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 ""` 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
```bash
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
```bash
agentrecord init --owner --display-name "Your Name"
```
This generates a baseline `agentrecord.config.json` containing output destinations, privacy options, and adapter setups.
#### 3. Advanced: Scan & Build
```bash
# 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
```bash
# 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**.
```text
โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ โโโโโโโโโโโโโโโโโ
โ 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 --owner --display-name "Name" [--no-account-usage]` |
| `init` | Initializes the local configuration schema. | `--dry-run --owner --display-name "Name" --profiles-dir --output ` |
| `scan` | Detects supported agent tools and local databases. | `--config --sessions-dir --opencode-db --claude-code-projects-dir ` |
| `build` | Generates structured JSON, MD, and HTML profiles. | `--config --owner --locale zh-CN --display-name "Name" --agent-context --no-account-usage --account-usage-timeout-ms --sessions-dir --opencode-db --opencode-data-dir --no-opencode --claude-code-projects-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 --owner ` |
| `doctor` | Checks environment, Node version, and database access. | `agentrecord doctor` |
---
## ๐ Expected Artifact Outputs
All generated profile outputs default to `profiles//`:
```text
profiles//
โโโ 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:
- [x] **Milestone 0: Repository Foundation** - Clean CLI package architecture, localization parity, and MIT release metadata.
- [x] **Milestone 1: Local CLI Baseline** - `init / scan / build / validate / open`, Codex local traces, privacy validation, and incremental state.
- [x] **Milestone 2: Shareable Proof Page** - Single-file `index.html` AI work passport with screenshot-ready share cards and editable display name.
- [x] **Milestone 3a: Active Local Adapters** - Codex, opencode, and Claude Code aggregate metadata adapters.
- [ ] **Milestone 3b: Additional Adapters** - OpenClaw, Hermes, and deeper adapter capability reporting.
- [x] **Milestone 4a: Agent Context Pack** - Optional `--agent-context` exports for future agent handoff.
*For full specifications, read [ROADMAP.md](./ROADMAP.md).*
---
## ๐ค Contributing
AgentRecord is open-source and welcomes contributions! To work with the code locally:
```bash
# 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](./docs/architecture.md) and [Privacy and Trust Specifications](./docs/privacy-and-trust.zh-CN.md).
---
## ๐ License
AgentRecord is licensed under the [MIT License](LICENSE).