Trace v1.5.0

Multi-agent version control for the AI economy.

Trace is a production-ready version control system designed for teams of AI agents. When multiple agents edit the same codebase simultaneously, Trace prevents collisions, maintains accountability, and ensures zero data loss.

🚀 Quick Start (2 minutes)

Install

npm install @zoebuildsai/trace@1.5.0

Initialize Repository

npx trace init /path/to/project

Basic Usage

# Create a snapshot
npx trace save "Added user authentication"

# View history
npx trace log --limit 10

# See what changed
npx trace status

# Restore to previous state
npx trace checkout <hash>

# Sync with remote
npx trace sync --push origin main

🎯 Use Cases

1️⃣ Single Agent (Simple Memory)

Agent takes snapshots of work and restores state as needed.

npx trace save "Processed batch of tickets"
npx trace sync --push
# Later...
npx trace log
npx trace checkout abc123

2️⃣ Two Agents (Serialized Access)

Agent A and B take turns editing the same file with locks.

# Agent A
npx trace lock src/api.ts
npx trace save "Added authentication"
npx trace unlock src/api.ts

# Agent B (blocked until A unlocks)
npx trace lock src/api.ts
npx trace save "Added authorization"
npx trace unlock src/api.ts

3️⃣ Multiple Agents (Parallel Work)

Many agents edit different files simultaneously without collision.

# Agent A (edits src/api.ts)
npx trace lock src/api.ts
npx trace save "Feature X"
npx trace unlock src/api.ts

# Agent B (edits src/utils.ts, in parallel)
npx trace lock src/utils.ts
npx trace save "Feature Y"
npx trace unlock src/utils.ts

# Both push
npx trace sync --push

📖 Command Reference

Core Commands

Command	Purpose
`trace init [dir]`	Initialize repository
`trace save -m "msg"`	Create snapshot
`trace log [--limit N]`	View history
`trace status`	Show changes
`trace checkout <hash>`	Restore state
`trace sync --push [remote]`	Sync with remote
`trace sync --pull [remote]`	Pull from remote

Multi-Agent Commands

Command	Purpose
`trace lock <file>`	Claim file for exclusive editing
`trace unlock <file>`	Release file lock
`trace audit [--agent ID]`	View who changed what
`trace collision-detect`	Find concurrent edits
`trace task register --agent ID --files X,Y`	Register agent task

Advanced Commands

Command	Purpose
`trace merge <branch>`	Merge branches
`trace rebase <onto>`	Rebase commits
`trace stash [save\|pop]`	Stash work
`trace cherry-pick <hash>`	Apply commit
`trace resolve <file>`	Resolve conflicts

Verification

Command	Purpose
`trace help`	Show all commands
`trace validate`	Verify files before push
`trace help <command>`	Help for specific command

🔒 Security Features

File Blocking

Sensitive files are automatically blocked from commits:

.env* (environment variables)
*.key, *.pem (cryptographic keys)
secrets.json, credentials.json (credentials)
password*, token* (sensitive data)

Pre-Commit Hook

Prevents accidental commits of sensitive files.

npx trace init
# → auto-installs pre-commit hook

Audit Trail

Complete history of who changed what:

npx trace audit --agent agent-a
# → Shows all changes by agent-a with timestamps

Workspace Isolation

Cannot escape repository boundary with ../../ paths.

⚡ Performance

All operations verified at sub-100ms:

Commit: <10ms
Lock/Unlock: <1ms
Collision Detection (100 files): <100ms
Log (1000 entries): <50ms
Checkout: <50ms
Push: <500ms (network dependent)

📋 File Structure

project/
├── .trace/          # Trace data
│   ├── objects/         # Snapshots
│   ├── refs/            # Branch pointers
│   └── config           # Settings
├── src/                 # Your code
├── tests/               # Your tests
└── .gitignore           # Git ignore patterns

🔄 Workflows

Workflow A: Parallel Development

Three agents work on different files simultaneously:

# Agent 1: edits src/auth.ts
npx trace lock src/auth.ts
npx trace save "Authentication module"
npx trace unlock src/auth.ts

# Agent 2: edits src/db.ts (parallel)
npx trace lock src/db.ts
npx trace save "Database connection"
npx trace unlock src/db.ts

# Agent 3: edits tests/main.test.ts (parallel)
npx trace lock tests/main.test.ts
npx trace save "Added unit tests"
npx trace unlock tests/main.test.ts

# All push together
npx trace sync --push

Workflow B: Sequential File Edits

Multiple agents queue for the same file:

# Agent A edits shared.ts
npx trace lock src/shared.ts
npx trace save "Update shared utilities"
npx trace unlock src/shared.ts

# Agent B waits for A, then edits
npx trace lock src/shared.ts  # Blocks until A unlocks
npx trace save "Extend utilities"
npx trace unlock src/shared.ts

# Agent C waits for B, then edits
npx trace lock src/shared.ts  # Blocks until B unlocks
npx trace save "Fix utilities"
npx trace unlock src/shared.ts

Workflow C: Conflict Detection

Automatic detection if multiple agents try same file:

# Agent A claims file
npx trace register-task --agent a --files src/main.ts

# Agent B tries same file
npx trace register-task --agent b --files src/main.ts
# → Returns "blocked by agent-a"

# Agent B waits
npx trace collision-detect --file src/main.ts
# → Shows A is editing it

# When A finishes
npx trace task complete
# → B automatically unblocks

🧪 Testing

Run the full test suite:

npm test
npm run test:watch      # Watch mode
npm run test:coverage   # Coverage report

Test Coverage:

1059+ tests (100% passing)
CLI commands: 45+ tests
Multi-agent coordination: 50+ tests
Conflict resolution: 70+ tests
Workspace isolation: 60+ tests
Integration workflows: 14+ tests

📦 Installation Options

Option 1: Global CLI

npm install -g @zoebuildsai/trace
trace init
trace save "snapshot"

Option 2: Local Project

npm install @zoebuildsai/trace
npx trace init
npx trace save "snapshot"

Option 3: In Code

import { Trace } from '@zoebuildsai/trace';

const trace = new Trace();
trace.commit('snapshot message');
trace.log(10);

🌐 remote Integration

Push snapshots to remote as a backup:

# Add remote remote
npx trace repo add origin https://remote.com/user/repo.git

# Push snapshots
npx trace sync --push origin main

# Pull snapshots
npx trace sync --pull origin main

# View history on remote
npx trace log

❓ FAQ

Q: Do I need git? A: No. Trace is standalone. remote sync is optional.

Q: What happens if an agent crashes? A: Locks timeout after 5 minutes automatically. Other agents can proceed.

Q: Can I roll back? A: Yes. npx trace checkout <hash> restores any previous state.

Q: Is it production-ready? A: Yes. 1059+ tests passing, <100ms performance verified, security hardened.

Q: What about large files? A: Trace handles files up to 100MB with compression (30-40% reduction).

Q: Can 1000+ agents use the same repo? A: Yes. Tested and verified. Collision detection and locking scales linearly.

📚 Documentation

RELEASE-NOTES-1.5.0.md — Complete feature list and performance metrics

💡 Examples

Example 1: Agent Memory Snapshots

# Agent starts work
npx trace init

# After processing 10 tickets
npx trace save "Processed 10 support tickets"

# After analyzing data
npx trace save "Completed market analysis"

# View what we did
npx trace log
# → Shows both commits with hashes and timestamps

Example 2: Team Collaboration

# Agent 1 works on authentication
trace lock src/auth.ts
trace save "Add 2FA support"
trace unlock src/auth.ts

# Agent 2 works on payments
trace lock src/payments.ts
trace save "Add Stripe integration"
trace unlock src/payments.ts

# Agent 3 works on tests
trace lock tests/integration.ts
trace save "Add end-to-end tests"
trace unlock tests/integration.ts

# Everyone pushes
trace sync --push

Example 3: Recovery

# Something went wrong
trace status

# See what's different
npx trace log

# Go back to last good state
npx trace checkout abc123def456

# Push the fix
npx trace sync --push

🛠️ Development

Requirements:

Node.js 16+
npm 7+

Build from source:

git clone https://github.com/zoebuildsai/trace.git
cd Trace
npm install
npm run build
npm test

📄 License

MIT — Free to use and modify.

👤 Author

Built by Zoë for autonomous agents.

🚀 Get Started Now

npm install @zoebuildsai/trace@1.5.0
npx trace init
npx trace help

Next step: Choose your workflow above and start using Trace.

Name		Name	Last commit message	Last commit date
Latest commit History 47 Commits
.trace		.trace
dist		dist
docs-website		docs-website
docs		docs
scripts		scripts
src		src
tests		tests
.gitignore		.gitignore
README.md		README.md
RELEASE-NOTES-1.5.0.md		RELEASE-NOTES-1.5.0.md
SKILL.md		SKILL.md
STATUS.md		STATUS.md
jest.config.js		jest.config.js
package.json		package.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Trace v1.5.0

🚀 Quick Start (2 minutes)

Install

Initialize Repository

Basic Usage

🎯 Use Cases

1️⃣ Single Agent (Simple Memory)

2️⃣ Two Agents (Serialized Access)

3️⃣ Multiple Agents (Parallel Work)

📖 Command Reference

Core Commands

Multi-Agent Commands

Advanced Commands

Verification

🔒 Security Features

File Blocking

Pre-Commit Hook

Audit Trail

Workspace Isolation

⚡ Performance

📋 File Structure

🔄 Workflows

Workflow A: Parallel Development

Workflow B: Sequential File Edits

Workflow C: Conflict Detection

🧪 Testing

📦 Installation Options

Option 1: Global CLI

Option 2: Local Project

Option 3: In Code

🌐 remote Integration

❓ FAQ

📚 Documentation

💡 Examples

Example 1: Agent Memory Snapshots

Example 2: Team Collaboration

Example 3: Recovery

🛠️ Development

📄 License

👤 Author

🚀 Get Started Now

About

Resources

Uh oh!

Stars

Watchers

Forks

Releases 1

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages