jean-claude 0.8.0
Jean Claude CLI - AI-powered development workflows for any codebase
License: MIT
Requires Python: >=3.10
Keywords: ai, automation, claude, cli, developer-tools, workflows

# Jean Claude CLI

> Universal AI Developer Workflows - Transform any project into an AI-driven development environment

Jean Claude (`jc`) is a CLI tool that enables programmatic AI agent orchestration for any codebase. Execute prompts, run multi-phase workflows, and monitor agent activity with a unified interface.

## Features

- **One-Command Setup**: `jc init` installs skill, updates CLAUDE.md, configures everything
- **Jean Claude CLI Skill**: 358-line comprehensive guide auto-installed to `.claude/skills/`
- **Two-Agent Workflow**: Opus plans features, Sonnet implements them
- **Coordinator Pattern**: Intelligent agent-to-human communication with smart escalation
- **Beads Integration**: Execute workflows directly from Beads tasks with `jc work`
- **Real-Time Streaming**: Watch agent output as it works with `--stream` mode
- **SDK-Based Execution**: Claude Agent SDK with Bedrock authentication
- **Workflow Composition**: Multi-phase SDLC workflows (plan → implement → verify → complete)
- **Git Worktree Isolation**: Safe parallel development without conflicts
- **Real-Time Telemetry**: SQLite event store with live monitoring UI
- **Push Notifications**: ntfy.sh integration for critical decision escalations
- **Multi-Project Support**: Project names in notifications when running multiple instances

## Installation

```bash
# Install with uv
uv pip install jean-claude

# Or install globally with uvx
uvx install jean-claude

# Verify installation
jc --version
```

## Quick Start

```bash
# Initialize Jean Claude in your project (one-time setup)
cd my-project/
jc init

# This creates:
# - .jc-project.yaml (configuration)
# - .claude/skills/jean-claude-cli/ (comprehensive CLI documentation skill)
# - .claude/commands/ (slash commands like /prime)
# - CLAUDE.md section (project-specific quick reference)
# - specs/, agents/, .jc/ directories

# Run an adhoc prompt
jc prompt "Analyze the codebase structure"

# Run a two-agent workflow (Opus plans, Sonnet implements)
jc workflow "Add user authentication with JWT"

# Or work on a Beads task directly
jc work jean_claude-2sz.4

# Run a simple chore workflow
jc run chore "Add error handling to login"
```

## Commands

### Core Commands

```bash
jc init                              # Initialize ADW in current project
jc prompt "your prompt here"         # Execute adhoc prompt
jc prompt "your prompt" --stream     # Stream output in real-time
jc run chore "task description"      # Run chore workflow
jc run feature "feature description" # Run feature workflow
```

### Two-Agent Workflow

The flagship workflow pattern: Opus plans, Sonnet implements.

```bash
# Full workflow (plan + implement)
jc workflow "Build user authentication"

# Use custom models
jc workflow "Complex feature" -i opus -c opus

# Run initializer and coder separately (modular approach)
jc initialize "Task description" -w my-workflow
jc implement my-workflow
```

### Coordinator Pattern (Agent-to-Human Communication)

Jean Claude implements a **coordinator pattern** where the main Claude Code instance intelligently triages agent questions, only escalating to you when truly needed.

**How it works:**
1. Sub-agents can call `ask_user` or `notify_user` tools when they need help
2. Messages appear in the workflow's INBOX directory
3. Coordinator (main Claude Code instance) sees questions and decides:
   - **Answer directly** (90% of cases) - Technical questions, test failures, code conventions
   - **Escalate to human** (10% of cases) - Business decisions, security, architecture choices
4. You only get ntfy push notifications for critical decisions

**Setting up ntfy notifications:**

```bash
# 1. Install ntfy app on your phone (iOS/Android/Web)
# 2. Choose a unique topic name
echo "jean-claude-$(openssl rand -hex 6)"

# 3. Subscribe to the topic in the ntfy app
# 4. Configure Jean Claude
export JEAN_CLAUDE_NTFY_TOPIC="your-topic-name"
```

See `NTFY_SETUP.md` and `docs/coordinator-pattern.md` for details.

**When you get escalated:**
- SSH to your machine
- Write response to `agents/{workflow-id}/OUTBOX/response.json`
- Agent receives your decision and continues

**Slash commands:**
- `/mailbox` - View and respond to agent messages (coordinator use)

### Beads Integration

Work directly from Beads tasks:

```bash
# Execute workflow from Beads task
jc work jean_claude-2sz.4

# Plan only, don't implement
jc work task-123 --dry-run

# Pause for approval after planning
jc work task-123 --show-plan

# Use Opus for both agents
jc work task-123 --model opus
```

### Monitoring & Status

```bash
jc status                            # Check workflow status
jc logs                              # View workflow event logs
jc dashboard                         # Start web monitoring dashboard
jc version                           # Display version information
```

### Project Management

```bash
jc init                              # Initialize new project (skill + CLAUDE.md + config)
jc migrate                           # Update existing project to latest version
jc prime                             # Gather project context
jc upgrade                           # Upgrade jc to latest version
jc upgrade --check                   # Check for updates only
```

**What `jc init` creates:**
- `.claude/skills/jean-claude-cli/` - Comprehensive CLI documentation skill
- `CLAUDE.md` section - Project-specific quick reference
- `.claude/commands/` - Slash commands (/prime, etc.)
- Configuration and directories

**What `jc migrate` does:**
- Installs missing skill
- Updates CLAUDE.md if needed
- Adds new slash commands
- Creates missing directories
- Safe for existing projects (doesn't overwrite)

### Cleanup

Keep your project clean by removing temporary files created by agents:

```bash
jc cleanup                           # Remove files older than 7 days
jc cleanup --age 14                  # Remove files older than 14 days
jc cleanup --all                     # Remove all temporary files
jc cleanup --agents                  # Also clean agent work directories
jc cleanup --dry-run                 # Preview what will be deleted
```

Temporary files are organized in `.jc/` subdirectories:
- `.jc/temp/` - Verification scripts (check_*.py, demo_*.py)
- `.jc/reports/` - Status reports (*_COMPLETE.md, *_VERIFICATION.md)
- `.jc/verification/` - Test outputs and logs

### Streaming Output

Real-time streaming displays output as the agent works:

```bash
# Stream output in real-time
jc prompt "Analyze the codebase" --stream

# Show tool uses and thinking process
jc prompt "Refactor authentication" --stream --show-thinking

# Different models with streaming
jc prompt "Quick question" --stream -m haiku
jc prompt "Complex analysis" --stream -m opus
```

**Benefits of streaming:**
- See progress in real-time as the agent works
- Better user experience for long-running prompts
- Optional visibility into tool uses and thinking process
- Graceful interrupt handling (Ctrl+C)

## Configuration

Jean Claude uses `.jc-project.yaml` for project-specific configuration:

```yaml
directories:
  specs: specs/
  agents: agents/
  trees: trees/
  source: src/
  tests: tests/

tooling:
  test_command: uv run pytest
  linter_command: uv run ruff check .

workflows:
  default_model: sonnet
  auto_commit: true
```

## Architecture

```
project/
├── agents/                     # Agent working directories
│   └── {workflow_id}/
│       ├── state.json          # Workflow state with features
│       └── events.jsonl        # Event log (JSONL format)
├── trees/                      # Git worktrees (isolated execution)
├── specs/                      # Workflow specifications
│   └── beads-{task_id}.md      # Auto-generated from Beads tasks
├── .jc/                        # Internal state and temporary files
│   ├── events.db               # SQLite event store
│   ├── temp/                   # Temporary verification scripts
│   ├── reports/                # Status and completion reports
│   └── verification/           # Test outputs and logs
└── .jc-project.yaml            # Project configuration
```

## Authentication

### Anthropic API

```bash
export ANTHROPIC_API_KEY="your-api-key"
```

### AWS Bedrock

```bash
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_PROFILE="your-profile"
export AWS_REGION="us-west-2"
```

## Development

```bash
# Clone and install
git clone https://github.com/joshuaoliphant/jean-claude
cd jean-claude
uv sync

# Run CLI in development
uv run jc --help
```

## Testing

Jean Claude has a focused test suite that tests OUR code, not external dependencies. We mock external tools like Beads rather than testing their implementation.

### Running Tests

```bash
# Run all tests (parallel execution)
uv run pytest

# Run with verbose output
uv run pytest -v

# Run specific test file
uv run pytest tests/test_work_command.py

# Run specific test class
uv run pytest tests/test_work_command.py::TestWorkCommand

# Run tests matching a pattern
uv run pytest -k "beads"

# Run with coverage
uv run pytest --cov=jean_claude --cov-report=html
```

### Test Organization

```
tests/
├── conftest.py                  # Root fixtures (cli_runner, mock_beads_task, etc.)
├── core/
│   ├── conftest.py              # Core module fixtures (sample_beads_task, subprocess mocks)
│   ├── test_beads*.py           # Beads model and integration tests
│   └── ...
├── orchestration/
│   ├── conftest.py              # Orchestration fixtures (workflow_state, execution_result)
│   ├── test_auto_continue.py    # Auto-continue workflow tests
│   └── test_two_agent.py        # Two-agent pattern tests
├── templates/
│   ├── conftest.py              # Template path fixtures
│   └── test_beads_spec.py       # Template tests
├── test_work_command.py         # CLI work command tests
├── test_dashboard.py            # Dashboard tests
└── ...
```

### Key Fixtures

| Fixture | Location | Purpose |
|---------|----------|---------|
| `cli_runner` | conftest.py | Click CLI testing |
| `mock_beads_task` | conftest.py | Standard BeadsTask for testing |
| `mock_beads_task_factory` | conftest.py | Factory for custom BeadsTask |
| `work_command_mocks` | conftest.py | All mocks for work command |
| `sample_beads_task` | core/conftest.py | Fully-populated BeadsTask |
| `mock_subprocess_success` | core/conftest.py | Subprocess mock for success |
| `mock_project_root` | orchestration/conftest.py | Temp project with agents/ dir |
| `sample_workflow_state` | orchestration/conftest.py | Pre-configured workflow state |

### Test Categories

- **Unit tests**: Test individual functions and classes
- **Integration tests**: Test CLI commands and workflows
- **Model tests**: Test Pydantic models and validation
- **Template tests**: Test Jinja template rendering

## Contributing

1. **Only test OUR code** - Mock external tools (Beads, etc.), don't test them
2. Write tests first (TDD approach)
3. Use existing fixtures from conftest.py files
4. Follow the mock patching rule: patch where used, not where defined
5. Run full test suite before submitting PR

## License

MIT