Agent Notebook

A local-first CLI tool for managing AI agent definitions in human-friendly Markdown.

What This Is

Agent Notebook helps developers:

• Define AI agents in structured Markdown with YAML frontmatter
• Generate agents.md — a single, standards-compliant file documenting all agents
• Track agent evolution via timestamped snapshots and semantic diffs
• Version agent behavior alongside code, using Git

What This Is NOT

• ❌ Not a SaaS or cloud service
• ❌ Not an agent execution runtime
• ❌ Not a UI dashboard
• ❌ No LLM API calls
• ❌ No telemetry or analytics

Everything runs locally, in your repo, under your control.

---

Installation

# Clone and build
git clone <repo-url>
cd agent-notebook
npm install
npm run build

# Link globally (optional)
npm link

Or run directly:

node dist/cli.js <command>

---

Quick Start

# Initialize agent notebook in your project
agent init

# Create a new agent interactively
agent new

# List all agents
agent list

# Generate agents.md
agent generate

# View changes since last snapshot
agent diff planner

# View history for an agent
agent history planner

---

Commands

agent init

Creates the .agent/ directory structure:

.agent/
├── agents/        # Your agent definitions
├── history/       # Version snapshots
├── config.json    # Notebook configuration
└── agents.md      # Auto-generated (gitignored)

agent new

Interactive wizard to create a new agent. Prompts for:

• Name, role, version
• Purpose
• Allowed/disallowed behaviors
• Inputs and outputs
• Notes

Creates a Markdown file in .agent/agents/.

agent list

Shows all agents with name, version, and role:

┌─────────────────────────────────────────────────────────────┐
│                        AGENTS                               │
├─────────────────────────────────────────────────────────────┤
│ Planner              v0.1.0     Breaks down tasks into...  │
│ Reviewer             v0.2.0     Reviews code for quality   │
└─────────────────────────────────────────────────────────────┘

agent generate

Reads all agent files, validates them, and generates .agent/agents.md.

This file is auto-generated and should not be edited manually.

agent diff <agent-name>

Compares the current agent file with its latest snapshot, showing semantic diffs grouped by section:

=== Frontmatter ===
- version: 0.1.0
+ version: 0.2.0

=== Purpose ===
+ Now includes risk assessment

agent history <agent-name>

List and manage historical snapshots:

# List all snapshots
agent history planner

# Restore a previous version
agent history planner restore

# Manually save current state
agent history planner save

---

Agent File Format

Each agent is defined in Markdown with YAML frontmatter:

---
name: Planner
role: Breaks down tasks into executable steps
version: 0.1.0
---

## Purpose
Help the developer reason clearly about implementation steps.

## Allowed
- Read existing code context
- Suggest refactors

## Disallowed
- Inventing requirements
- Writing secrets

## Inputs
- Feature descriptions
- Bug reports

## Outputs
- Step-by-step plans
- Risk notes

## Notes
This agent should be conservative and verbose.

Required fields: name, role, version (semver)

---

Project Structure

.agent/
├── agents/
│   ├── planner.md
│   ├── reviewer.md
│   └── <agent>.md
├── history/
│   └── <agent-name>/
│       ├── 2024-01-15-1430.md
│       └── ...
├── config.json
└── agents.md   (auto-generated)

---

Philosophy

Local-First

Everything stays in your repo. No cloud, no accounts, no network.

Human-First

Agent definitions are Markdown, the universal format. Edit them in any text editor. Review them in any diff tool. They're just text files.

Git-Friendly

All files are human-readable text. History is tracked via Git-compatible snapshots. The generated agents.md is gitignored to avoid conflicts.

Separation of Concerns

• Source of truth: Individual agent Markdown files in .agent/agents/
• Generated output: .agent/agents.md (never edit directly)
• History: Immutable snapshots in .agent/history/

---

Development

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Watch mode
npm run dev

Testing

The test suite uses Vitest with real filesystem operations (no mocks):

npm test            # Run all tests
npm run test:watch  # Watch mode

---

Requirements

• Node.js 18+
• npm or yarn

---

License

MIT