Claude-Agent-OS

AI-powered product development assistant with conversational planning and spec-driven workflows

Version 0.1.0 (Development) | Installation | Features | GitHub

What is Claude-Agent-OS?

Claude-Agent-OS combines two powerful systems for AI-assisted software development:

1. PDA (Product Design Assistant): Conversational interface for brainstorming product ideas, refining concepts, and generating comprehensive product documentation through natural dialogue
2. Agent-OS Workflows: Spec-driven development system with structured workflows for planning, specification, and implementation

Key Features

• Conversational Product Design: Natural dialogue with specialist AI agents (strategy, research, design, technical)
• Knowledge Accumulation: Builds understanding of your product across conversation turns
• Document Generation: Automatically creates PRDs, user stories, research reports, design specs
• Spec-Driven Workflows: Structured plan-product, new-spec, create-spec, implement-spec workflows
• Multi-Agent Orchestration: Coordinate specialized agents for complex tasks
• 100% Test Coverage: 602 passing tests across all systems
• Production-Ready: CLI, Claude API integration, configuration management

Installation

Development Installation

# Clone the repository
git clone https://github.com/jcmrs/claude-agent-os.git
cd claude-agent-os

# Install dependencies
npm install

# Build the project
npm run build

# Set up environment
cp .env.example .env
# Edit .env and add your ANTHROPIC_API_KEY

Configuration

Create a .env file in the project root:

# Required: Your Anthropic API key
ANTHROPIC_API_KEY=your_api_key_here

# Optional: Override default model (default: claude-sonnet-4)
# ANTHROPIC_MODEL=claude-sonnet-4

Get your API key from Anthropic Console

Usage

CLI Commands

# View available commands
node dist/cli/index.cjs --help

# Initialize project structure
node dist/cli/index.cjs init

# Check system health
node dist/cli/index.cjs doctor

# View project status
node dist/cli/index.cjs status

# List available workflows
node dist/cli/index.cjs list

Workflow Commands

# Plan a product (creates mission, roadmap, tech stack)
node dist/cli/index.cjs plan-product

# Initialize new feature spec
node dist/cli/index.cjs new-spec "user authentication"

# Create detailed specification
node dist/cli/index.cjs create-spec agent-os/specs/2025-01-10-auth

# Implement specification
node dist/cli/index.cjs implement-spec agent-os/specs/2025-01-10-auth

PDA (Product Design Assistant)

The PDA provides conversational product design through specialized AI agents:

import { Orchestrator, SessionManager, KnowledgeBase, /* ... */ } from '@claude/agent-os';

// Create PDA session
const sessionManager = new SessionManager('./sessions');
const session = await sessionManager.createSession('My Product Idea');

// Have conversation with specialist agents
const response = await orchestrator.processTurn(
  session.id,
  "I want to build a task management app for remote teams"
);

// Generate documents from accumulated knowledge
const prd = await orchestrator.generateDocument(session.id, 'PRD');
const userStories = await orchestrator.generateDocument(session.id, 'UserStories');

Architecture

Dual System Design

Claude-Agent-OS integrates two complementary systems:

PDA (Product Design Assistant)

• Conversational interface for product ideation and refinement
• Specialist AI agents: Strategy, Research, Design, Technical
• Knowledge accumulation across conversation turns
• Document generation: PRDs, user stories, research reports, design specs
• Session management for persistent conversations

Agent-OS Workflows

• Spec-driven development methodology
• Structured workflows: plan-product, new-spec, create-spec, implement-spec
• Multi-agent orchestration for complex tasks
• Integration with Claude API via @anthropic-ai/claude-agent-sdk

Project Structure

claude-agent-os/
├── src/
│   ├── cli/                    # CLI commands and utilities
│   ├── pda/                    # Product Design Assistant
│   │   ├── core/              # Session, Knowledge Base, Orchestrator
│   │   ├── agents/            # Specialist agents (Strategy, Research, etc.)
│   │   ├── documents/         # Document generators (PRD, UserStories, etc.)
│   │   └── prompts/           # AI prompts and templates
│   ├── agent-os/              # Spec-driven workflow system
│   │   ├── commands/          # Workflow commands (plan-product, etc.)
│   │   ├── planning/          # Product planning workflows
│   │   ├── spec/              # Specification workflows
│   │   └── workflows/         # Core workflow engine
│   ├── orchestration/         # Multi-agent orchestration layer
│   ├── types/                 # TypeScript type definitions
│   └── utils/                 # Shared utilities
├── dist/                      # Built output (CommonJS)
├── package.json
└── .env                       # Configuration (ANTHROPIC_API_KEY)

Testing

100% Test Coverage - 602 passing tests across 27 test files:

• Unit tests for all core components
• Integration tests for PDA and workflows
• End-to-end workflow tests
• Template and configuration validation

Run tests: npm test

Requirements

• Node.js: 20.0.0+ required
• Anthropic API Key: Required for Claude integration (Get API key)
• npm: Required for dependency management
• Git: Optional, for version control operations

Development

Build Commands

npm run build         # Build TypeScript to dist/
npm run dev           # Watch mode for development
npm run typecheck     # TypeScript type checking
npm run lint          # ESLint checks
npm run format        # Prettier formatting

Testing

npm test                    # Run all 602 tests
npm run test:coverage       # Run tests with coverage report

Current Status: 602/602 tests passing (100% coverage)

• 27 test files covering all core systems
• Unit tests for PDA, Agent-OS, orchestration
• Integration tests for workflows
• End-to-end workflow validation

Version History

v0.1.0 (Current - Development)

Development Release - Not yet published to npm

Implemented Features:

• ✅ PDA System: Complete conversational product design assistant
  • Session management with persistent conversations
  • Specialist AI agents (Strategy, Research, Design, Technical)
  • Knowledge accumulation across conversation turns
  • Document generators (PRD, User Stories, Research Reports, Design Specs)
  • Intent extraction and agent selection
• ✅ Agent-OS Workflows: Spec-driven development system
  • Product planning workflows (mission, roadmap, tech stack)
  • Specification workflows (new-spec, create-spec, implement-spec)
  • Multi-agent orchestration layer
  • Template engine and validation
• ✅ Production Infrastructure:
  • CLI with all commands (init, doctor, status, list, run, workflows)
  • Claude API integration via @anthropic-ai/claude-agent-sdk
  • Configuration management system
  • 100% test coverage (602/602 passing tests)
• ✅ TypeScript Core: Full TypeScript implementation with type safety

Next Steps:

• [ ] Publish to npm registry
• [ ] Create release documentation
• [ ] Add usage examples and tutorials

License

MIT License - See LICENSE file for details

Acknowledgments

Inspired by agent-os by Brian Casel at Builder Methods.

Support

• Issues: GitHub Issues
• Source: GitHub Repository