Shiplog

A ship's log tracks every voyage. Shiplog tracks every dev session.

Shiplog is a Claude Code plugin that gives every project persistent memory, automatic progress tracking, and background quality agents — so no session starts cold and no decision is forgotten.

No planning required. Just build. Shiplog watches your commits and auto-discovers features, logs architecture decisions, reviews security, and tracks patterns — all in the background.

The Problem

Claude Code sessions are stateless. Over 50+ sessions, you lose context: what was built, what decisions were made, what's left, what security issues exist. You re-explain the project every time, waste tokens, and forget past decisions.

The Solution

Shiplog automatically:

1. Auto-discovers features from your commits — no upfront PRD needed (vibe mode)
2. Reads progress at session start so Claude picks up where you left off
3. Launches background agents after each commit to update specs, PRD status, security reviews, and memory
4. Maintains code pattern docs so Claude writes consistent code across sessions

Install

Run inside a Claude Code session:

/plugin marketplace add aadivar/shiplog
/plugin install shiplog@shiplog

Quick Start

# Initialize on your project (pick vibe mode — no planning needed)
/shiplog init

# Just start building. Features are auto-discovered from your commits.
# Or define one manually:
/shiplog feature "user authentication"

# Check project status anytime
/shiplog status

What a typical session looks like

User: Let's add the invoice PDF generation feature

Claude: [reads PROGRESS.md automatically]
I see we're on Sprint 2, working on the billing module.
Last session we finished the invoice list view (F008).

Let me create the feature file and start building...
[creates docs/features/F009-invoice-pdf.md]
[builds the feature]
[after commit, background agents run silently]

User: /shiplog status

Shiplog Status — Acme SaaS
━━━━━━━━━━━━━━━━━━━━━━━━━━
Sprint: 2 | Active: F009 (in-progress) | 12/24 features done
  Phase 1 (Foundation): ████████████ 100%
  Phase 2 (Core):       ████████░░░░  67%
  Phase 3 (Advanced):   ░░░░░░░░░░░░   0%
  Last security review: clean (2026-03-03)

Tracking Modes

Choose during /shiplog init:

Mode	How it works	Best for
Vibe mode (default)	Just build. PRD agent auto-discovers features from your commits. No upfront planning.	Solo devs, prototyping, hackathons, exploration
Planned mode	Define features in PRD first, then build. Agent tracks status as you go.	Teams, client projects, structured sprints

Both modes get the same background agents. You can always add manual features with /shiplog feature in either mode.

Background Agents

After each git commit, Shiplog silently runs 4 background agents:

Agent	What it does	Output
Specs	Logs architecture decisions automatically	docs/SPECS.md
PRD	Auto-discovers features from diffs + updates statuses	docs/PRD.md
Security	Reviews for OWASP Top 10, hardcoded secrets, injection risks	docs/SECURITY.md
Memory	Maintains code patterns and project memory	Claude memory files

Agents run in the background with run_in_background: true — they never interrupt your work.

Commands

Command	Description
/shiplog init	Initialize Shiplog on current project
/shiplog status	Show project dashboard (sprint, features, completion %)
/shiplog feature <name>	Create a new feature from template
/shiplog sprint <n>	Start a new sprint with archival
/shiplog review	Manually trigger all background agents
/shiplog config	View/edit Shiplog configuration
/shiplog agent <name>	Create a custom background agent
/shiplog agent list	List all agents (built-in + custom)
/shiplog upgrade	Pull latest version from GitHub

Project Structure

When you run /shiplog init, it scaffolds:

docs/
├── PRD.md              # Feature roadmap with status tracking
├── SPECS.md            # Architecture decisions log
├── SECURITY.md         # Security review audit trail
├── PROGRESS.md         # Session log + current focus
├── features/           # Per-feature detail files
└── archive/            # Archived sprint logs

.shiplog/
├── config.json         # Plugin settings
└── agents/             # Custom agent definitions

And appends an orchestration section to your CLAUDE.md (never overwrites).

Configuration

Stored in .shiplog/config.json:

{
  "agents": {
    "model": "haiku",
    "specs": { "enabled": true },
    "prd": { "enabled": true },
    "security": { "enabled": true },
    "memory": { "enabled": true },
    "custom": []
  },
  "orchestration": {
    "readProgressOnStart": true,
    "launchAgentsAfterTask": true,
    "triggerMethod": "hooks+claude.md",
    "maxParallelAgents": 3
  }
}

Agent Models

Choose during /shiplog init or change with /shiplog config:

• haiku (default) — Fastest and cheapest, great for background agent work
• sonnet — More capable analysis
• opus — Most capable, highest cost

Custom Agents

Create your own background agents that run alongside the built-in ones:

/shiplog agent "a11y-reviewer"

This creates .shiplog/agents/a11y-reviewer-agent.md with an editable prompt. Your agent runs automatically after each commit, just like the built-in ones.

Examples: accessibility reviewer, performance auditor, dependency checker, test coverage tracker.

How It Works

Shiplog uses a hybrid triggering approach:

1. Hooks (reliable backbone) — PostToolUse hooks fire after git commits and launch background agents automatically
2. CLAUDE.md (flexible layer) — Instructions in CLAUDE.md handle session-start context loading (reading PROGRESS.md, displaying status)

New session starts
    → CLAUDE.md instructs Claude to read docs/PROGRESS.md
    → Claude displays status and has full project context

User works and commits
    → PostToolUse hook fires
    → Hook reads .shiplog/config.json
    → Launches enabled agents in background
    → Agents update docs silently

Privacy & Security

• All data stays local (docs/ directory in your repo, memory in ~/.claude/)
• No external API calls, no telemetry
• Security agent reviews for leaked secrets but never logs actual values
• .gitignore docs/ if you don't want it committed

Plugin Structure

├── .claude-plugin/plugin.json   # Plugin manifest
├── skills/shiplog/SKILL.md      # Session orchestration
├── commands/                    # Slash commands
├── agents/                      # Built-in agent prompts
├── hooks/                       # PostToolUse hook config + script
├── templates/                   # Handlebars templates for scaffolding
├── scripts/                     # Stack detection, config validation
├── settings.json                # Default permissions
├── SKILL.md                     # Top-level entry point
└── LICENSE

Roadmap

Done

• Project initialization with stack detection (/shiplog init)
• Background agents — Specs, PRD, Security, Memory
• PostToolUse hooks for automatic agent triggering
• Session context restoration from PROGRESS.md
• Feature scaffolding (/shiplog feature)
• Sprint management with archival (/shiplog sprint)
• Status dashboard (/shiplog status)
• Custom agent creation (/shiplog agent)
• Configuration management (/shiplog config)
• Manual agent trigger (/shiplog review)

Up Next

• Agent output summarization — show a brief digest of what agents found after they complete
• /shiplog diff — show what changed across sessions in docs
• Smarter feature-to-file mapping — agents auto-link features to source files
• /shiplog retro — generate a sprint retrospective from session logs
• Conflict detection — warn when multiple agents edit the same section
• Agent performance metrics — track how often agents produce useful entries vs noise

Future

• Team mode — shared docs across contributors with merge-safe formats
• CI integration — run security agent in GitHub Actions
• Dashboard web UI — visual project status beyond the terminal
• Official Anthropic marketplace listing
• VS Code / JetBrains extension for Shiplog status in the sidebar

Requirements

• Claude Code v1.0+
• Git repository (agents use git diff for change detection)
• Works with any language/framework

License

MIT — Open source, free forever.