Claw

MCP server and CLI for workflow and ECM capabilities that externalize and inject context across Claude sessions.

Problem

Building complex software with AI agents requires maintaining context across multiple sessions, ensuring quality through exemplars, and coordinating different agent roles throughout the SDLC.

Solution

Claw provides:

• User stories and subtasks enabling finessed code exemplars to help agents triangulate
• Workflow orchestration for specification, design, planning, coding, reviews, showcases and retrospective
• Knowledge cartridges and templates for consistent patterns and standardise documentation handlebar templates (including prompts)
• Document management with versioning and editing
• Multi-agent coordination for different SDLC roles

Tech Stack

• Bun
• TypeScript

Target Audience

Solo developers building high-quality software with AI assistance.

Getting Started

Installation

# Install globally
npm install -g @kelceyp/claw

# Verify installation
claw --version
claw-mcp --version

CLI Usage

The claw CLI allows you to create and read knowledge cartridges from the command line.

Create Cartridges

# Create a shared cartridge (available to all projects)
claw cartridge create --scope=shared --name=testing-patterns.md --content="# Testing Patterns

Use TDD."

# Create a system cartridge (system-level)
claw cartridge create --scope=system --name=core-principles.md --content="# Core Principles

Fail fast."

# Create a project cartridge (project-specific)
claw cartridge create --scope=project --name=database/kysely.md --content="# Kysely Patterns

Use transactions."

# Create with nested directories
claw cartridge create --scope=shared --name=frontend/react/hooks.md --content="# React Hooks

Use useEffect sparingly."

# Read content from stdin
cat my-cartridge.md | claw cartridge create --scope=shared --name=my-cartridge.md --content -

# Multi-line content via stdin
claw cartridge create --scope=shared --name=long-doc.md --content - <<EOF
# Long Document

Multiple lines
of content here.
EOF

Read Cartridges

# Read a shared cartridge
claw cartridge read --scope=shared --name=testing-patterns.md

# Read a project cartridge
claw cartridge read --scope=project --name=database/kysely.md

# Read a system cartridge
claw cartridge read --scope=system --name=core-principles.md

MCP Server Configuration

Add to your Claude Desktop configuration (claude_desktop_config.json):

For Development (Local Code)

{
  "mcpServers": {
    "claw-dev": {
      "command": "bun",
      "args": ["/path/to/claw/src/mcp/main.ts"],
      "env": {
        "DEBUG": "claw:*"
      }
    }
  }
}

For Production (Installed Package)

{
  "mcpServers": {
    "claw": {
      "command": "npx",
      "args": ["@kelceyp/claw-mcp"],
      "env": {
        "DEBUG": "claw:*"
      }
    }
  }
}

For Project-Specific Working Directory

{
  "mcpServers": {
    "claw": {
      "command": "npx",
      "args": ["@kelceyp/claw-mcp"],
      "cwd": "/Users/user/Dev/myapp",
      "env": {
        "DEBUG": "claw:*"
      }
    }
  }
}

MCP Tools

Once configured, Claude can use these tools:

• cartridge_create: Create a knowledge cartridge (file stored in ~/.claw/)
• cartridge_read: Read a knowledge cartridge

Example usage in Claude:

Create a cartridge called "testing-patterns.md" in shared scope with content about TDD.

Configuration

.claw.json

The .claw.json configuration file allows you to customize claw's behavior on a per-project basis.

Schema (v1)

{
  "dataDir": "/absolute/path/to/data/directory"
}

Fields

dataDir (optional)

Type: string (absolute path) Default: ~/.claw/ Introduced: Phase 5 (Subtask 016) Status: Test infrastructure only (CLI/MCP parsing not yet implemented)

Specifies an alternative data directory where claw stores all cartridges, workflows, and other data.

Requirements:

• MUST be an absolute path (relative paths are not supported)
• Directory will be created automatically if it doesn't exist
• Parent directory must exist and be writable

Use Cases:

1. Test Isolation: E2E and blitz tests use dedicated data directories to avoid polluting production ~/.claw/
2. Multi-Environment Development: Separate data directories for different projects or environments
3. CI/CD: Isolated test runs with ephemeral data directories

Examples:

{
  "dataDir": "/home/node/.claw-test-dev"
}

{
  "dataDir": "/Users/developer/projects/my-app/.claw-data"
}

{
  "dataDir": "/tmp/claw-ci-run-12345"
}

Behavior When Missing

Current (Phase 5):

• If .claw.json does not exist, claw defaults to ~/.claw/
• Only test scripts currently use .claw.json (installation scripts create it for test environments)

Future (Post-Phase 5):

• CLI and MCP will parse .claw.json when present
• Implementation deferred to future subtask

Location

The .claw.json file should be placed in the project root (the directory where package.json exists for npm-installed projects).

Example project structure:

my-project/
├── package.json
├── .claw.json          # Configuration file
├── .mcp.json           # MCP server configuration
└── node_modules/
    └── @kelceyp/
        └── claw/

Testing Usage

In Docker-based E2E tests, .claw.json is created by installation scripts:

Dev Variant:

# test/e2e-&-blitz-docker-setup/server-dist/install.sh creates:
{
  "dataDir": "/home/node/.claw-test-dev"
}

NPM Variant:

# test/e2e-&-blitz-docker-setup/npm-version/install.sh creates:
{
  "dataDir": "/home/node/.claw-test-npm"
}

This isolation ensures:

• Tests never touch production ~/.claw/ directory
• Dev and npm test variants use separate data directories
• Test data is cleaned up when container is destroyed
• Installation script becomes a tested component

Security Considerations

• Path Traversal: Future implementation will validate that dataDir paths don't escape intended boundaries
• Permissions: Directory must be readable and writable by the user running claw
• Symlinks: Symlinks in dataDir path will be resolved and validated (future implementation)

Migration Notes

Phase 5 (Current):

• .claw.json is created by test infrastructure only
• CLI/MCP do not yet parse this file
• All production usage still defaults to ~/.claw/

Future Phases:

• CLI/MCP will read and honor .claw.json configuration
• Additional configuration fields may be added (e.g., logging, plugins, etc.)
• Schema versioning may be introduced if breaking changes are needed

Related Documentation

• Test Infrastructure: test/e2e-&-blitz-docker-setup/README.md
• Installation Scripts:
  • test/e2e-&-blitz-docker-setup/server-dist/install.sh
  • test/e2e-&-blitz-docker-setup/npm-version/install.sh
• Testing Strategy: Story 002 design documents

Changelog

v1 (Phase 5 - Subtask 016):

• Initial schema with dataDir field
• Used by test infrastructure only
• CLI/MCP parsing deferred to future subtask

Future Commands

@todo - these are examples and will likely evolve

claw project initialise

# Story management
claw story create --summary="My Story Summary"
claw story state set "in-progress"

# Workflow execution
claw workflow run system/workflow/story-specification-workflow.md --method="interview user"
claw workflow run system/workflow/story-design-workflow.md --method="yolo mode"

# Document operations
claw document edit stories/004-my-story-summary/spec.md
claw document edit --id=4 --replace="{'old-content': '...', 'new content': '...'}"

# Subtasks
claw subtask create --storyId=4 --summary="My first subtask" --method="interview user"

^ mcp tool equivalents for claude

Project Structure

This project contains the source code for the system.

This project

├── .git
├── .env
├── src/
├── test/
├── package.json
├── etc.

Claw data folder

Claw creates this folder in the user's home folder and uses git for version control. It is created lazily upon first usage.

~/.claw/  
├── .git
├── system/
│   ├── workflows/
│   │   ├── story-specification.md
│   │   └── etc.
│   ├── cartridges/
│   │   ├── kysley.md
│   │   ├── tdd-runbook.md
│   │   └── etc.
│   └── templates/
│       ├── story-specification.md
│       └── etc.
├── shared/
│   ├── workflows/
│   │   ├── etc.
│   ...
├── projects/

Claw project data

Claw creates this sub-folder in the user's home folder and uses git for version control. It is created lazily upon first usage

~/.claw/
├── projects/
├── stories/
│   └── 004-my-story-summary/
│       ├── spec.md
│       ├── design.md
│       ├── plan.md
│       └── subtasks/
└── workslips/
    └── story-specification-workflow/
        └── 003-workslip/
            ├── 001-task/
            │   ├── prompt.txt
            │   ├── output.json
            │   └── planning-notes.md
            └── 002-task/
            
~/users-project/
├── .claude/
├── .mcp.json   <-- specifies npm @kelceyp/claw package
├── claude.md
├── readme.md
├── node_modules/
├── package.json   <-- npm @kelceyp/claw package could be here if not installed globally

Dev versus prod

A claw developer could refer to the claw project folder (i.e. this folder) directly to configure a claw-dev mcp connector bypassing npm publishing for quick turnaround. Building a bun distribution, npm publishing, installing via nmp (globally or locally) and referencing this as claw in the .mcp.json is the typical 'prod' usage.