Claude Projects


Multi-project manager for Claude Code - Dispatch tasks across multiple projects with background execution and batch processing.

``bash
npm install -g claude-projects
`

Key Features

- Background Execution - Run tasks in the background and check on them later
- Real-time Log Streaming - Watch Claude's output live as tasks execute
- Batch Processing - Execute multiple tasks across different projects from a YAML file
- Central Config - Manage all your projects in one place
- Task Management - Track, monitor, and control running tasks

Problem

When working with multiple projects using Claude Code, you typically need to:
1. Navigate to each project directory
2. Start a Claude session
3. Give your instructions
4. Repeat for each project

This gets tedious when managing multiple projects simultaneously.

Solution

Run tasks across multiple projects, in the background, or batch process them all at once:

`bash


Single task

ccode my-app "implement dark mode"

Background execution - work on multiple projects simultaneously

ccode my-app "implement dark mode" --background
ccode another-project "run tests and fix failures" --background
ccode web-app "refactor authentication" --background

Check status of all background tasks

ccode status

Batch process - run multiple tasks from a YAML file

ccode batch tasks.yaml
`

Example batch file (tasks.yaml):
`yaml
my-app: "implement dark mode"
another-project: "run tests and fix failures"
web-app: "refactor the authentication module"
mobile-app: "update dependencies"
`

Installation

Install globally via npm:

`bash
npm install -g claude-projects
`

That's it! The ccode command is now available globally.

$3

You can also use npx to run commands without installing:

`bash
npx claude-projects init
npx claude-projects list
npx claude-projects my-app "run tests"
`

$3

Click to expand source installation instructions

`bash
git clone https://github.com/Mansuro/claude-projects.git
cd claude-projects
npm install
npm run build
npm link
`

Quick Start

$3

`bash
ccode init
`

This creates ~/.claude-projects.yaml with sample projects.

$3

Open ~/.claude-projects.yaml and add your projects:

`yaml
projects:
my-app:
path: ~/workspace/my-app
description: My awesome application

another-project:
path: ~/workspace/another-project
description: Another project
defaultArgs:
- --continue # Optional: always continue last session

settings:
claudePath: claude # Path to claude executable
timeout: 300000 # 5 minutes timeout
`

$3

`bash
ccode list
`

$3

`bash


Run a task (foreground)

ccode my-app "add user authentication"

Run tasks in background - work on multiple projects at once

ccode my-app "implement dark mode" --background
ccode another-project "run tests" --background

Check background task status

ccode status

View logs for a specific task

ccode logs task-1234567890-abc123

Watch logs in real-time as Claude works (like tail -f)

ccode logs task-1234567890-abc123 --follow
`

$3

Create a tasks.yaml file:

`yaml
my-app: "implement dark mode"
another-project: "run tests and fix failures"
web-app: "update dependencies"
`

Run all tasks:

`bash
ccode batch tasks.yaml
`

All tasks run in background by default. Check progress with ccode status.

Features

$3

- Project Registry: Manage multiple projects in one YAML config
- Quick Project Add: Add projects with a simple command (like npm install)
- Task Dispatch: Run Claude commands in any project from anywhere
- Background Execution: Run tasks in the background with --background flag
- Real-time Log Streaming: Watch Claude's output live with --follow flag
- Batch Processing: Execute multiple tasks from a YAML file
- Task Management: Track, monitor, and control background tasks
- Detailed Logging: Full Claude output captured to log files
- Path Resolution: Handles ~ and relative paths automatically
- Dry Run Mode: Preview commands before execution
- Project Descriptions: Document what each project does
- Default Arguments: Set per-project Claude arguments

$3

- Interactive Project Picker: TUI menu to browse and select projects
- Session Management: Track and resume sessions per project
- Parallel Execution: Run same task across multiple projects
- Project Templates: Initialize new projects with common configs
- Context Sharing: Define shared knowledge between related projects
- Alias Support: Create shortcuts for common tasks
- Git Integration: Auto-detect git repos and their status

Commands

$3

Create a sample config file at ~/.claude-projects.yaml

`bash
ccode init
`

$3

List all configured projects

`bash
ccode list
`

$3

Add a new project to the config. Similar to npm install for dependencies.

`bash


Add current directory as a project

ccode add my-project

Add a specific directory

ccode add my-project ~/workspace/my-project

Add with description

ccode add my-project ~/workspace/my-project -d "My awesome project"
ccode add my-project ~/workspace/my-project --description "My awesome project"
`

Arguments:
- name (required) - Name for the project
- path (optional) - Path to project directory (defaults to current directory)

Options:
- -d, --description - Project description

$3

Remove a project from the config. Alias: rm

`bash
ccode remove my-project
ccode rm my-project # Short form
`

$3

Execute a task in a specific project

`bash


Basic (foreground)

ccode my-app "list all TypeScript files"

Background execution

ccode my-app "implement dark mode" --background
ccode my-app "implement dark mode" -b # Short form

With dry-run

ccode my-app "implement feature X" --dry-run

With verbose output

ccode my-app "run tests" --verbose
`

Options:
- -b, --background - Run task in background
- -v, --verbose - Show verbose output
- --dry-run - Show what would be executed without running

$3

Execute multiple tasks from a YAML file. All tasks run in background by default.

`bash


Run tasks from file

ccode batch tasks.yaml

Run tasks in foreground (not recommended)

ccode batch tasks.yaml --no-background
`

File format (YAML):
`yaml
project-name: "task description"
another-project: "another task"
my-app: |
Multi-line task description
with multiple lines
`

See example-tasks.yaml for a complete example.

$3

Show status of background tasks

`bash


Show running and recent tasks (last 24 hours)

ccode status

Show all tasks

ccode status --all
`

$3

View logs for a background task

`bash


View logs

ccode logs task-1234567890-abc123

Follow logs (like tail -f)

ccode logs task-1234567890-abc123 --follow
ccode logs task-1234567890-abc123 -f # Short form
`

$3

Stop a running background task

`bash
ccode kill task-1234567890-abc123
`

$3

Remove old completed tasks (older than 7 days)

`bash
ccode cleanup
`

Configuration

$3

~/.claude-projects.yaml

$3

`yaml
projects:
project-name:
path: ~/path/to/project # Required: project directory
description: Description here # Optional: project description
defaultArgs: # Optional: default Claude arguments
- --continue
- --another-flag

settings:
claudePath: claude # Optional: path to Claude executable (default: 'claude')
timeout: 300000 # Optional: timeout in ms (default: 300000)
`

$3

Paths in the config can use:
- Tilde expansion: ~/workspace/my-project
- Absolute paths: /Users/username/projects/my-project
- Relative paths: workspace/my-project (relative to home directory)

Use Cases

$3

`bash


Navigate to a project directory

cd ~/workspace/my-new-project

Add it to claude-projects

ccode add my-new-project -d "My new side project"

Now you can run tasks from anywhere

ccode my-new-project "analyze the codebase structure"
`

$3

`bash


Run tasks in background

ccode client-a "update the landing page" -b
ccode client-b "fix the authentication bug" -b
ccode client-c "add new payment method" -b

Check status of all tasks

ccode status
`

$3

`bash


Create a tasks file

cat > daily-tasks.yaml <client-a: "run tests and fix any failures"
client-b: "update dependencies and run security audit"
client-c: "generate weekly analytics report"
EOF

Execute all tasks in background

ccode batch daily-tasks.yaml

Monitor progress

ccode status
`

$3

`bash


Run tasks across different parts of the monorepo

ccode frontend "update the header component" -b
ccode backend "add new API endpoint" -b
ccode mobile "sync with latest API changes" -b

View logs for specific task

ccode logs task-1234567890-abc123 --follow
`

$3

`bash


Work on multiple features simultaneously

ccode app-feature-auth "implement OAuth" -b
ccode app-feature-payments "integrate Stripe" -b
ccode app-bugfix "fix memory leak in worker" -b

Check which tasks completed

ccode status --all
`

How It Works

$3

1. Config Loading: Reads ~/.claude-projects.yaml to get project definitions
2. Path Resolution: Resolves project path (handles ~, relative paths)
3. Directory Validation: Ensures the project directory exists
4. Command Execution: Spawns Claude in the project directory with your task as input
5. Output Streaming: Shows Claude's output in real-time

$3

1. Task Creation: Generates unique task ID and creates log file
2. Process Spawning: Launches Claude as a detached background process
3. Log Recording: All output is written to ~/.claude-projects/logs/.log
4. Task Tracking: Stores task metadata in ~/.claude-projects/tasks.json
5. Process Monitoring: Automatically updates task status when process completes

Background Task Lifecycle:
- running → Task is actively executing
- completed → Task finished successfully (exit code 0)
- failed → Task finished with error (non-zero exit code)
- killed → Task was manually stopped with ccode kill

Requirements

- Node.js: 18.0.0 or higher
- Claude Code: Must be installed and accessible via claude command
- Operating System: macOS, Linux, or Windows (WSL)

Development

$3

`bash
git clone https://github.com/yourusername/claude-projects.git
cd claude-projects
npm install
npm run build
`

$3

`bash
npm run dev # Watch mode - auto-rebuild on changes
`

$3

`bash
npm link # Install globally from local build
`

$3

`
claude-projects/
├── src/
│ ├── cli.ts # CLI entry point (commander setup)
│ ├── config.ts # Config file loading and validation
│ ├── dispatcher.ts # Task execution logic
│ ├── types.ts # TypeScript interfaces
│ └── index.ts # Main exports
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.md
`

Troubleshooting

$3

Run ccode init to create the config file, then edit ~/.claude-projects.yaml.

$3

Check that the path in your config file is correct. Paths are resolved relative to your home directory unless absolute.

$3

Ensure Claude Code is installed and the claude command is in your PATH. You can specify a custom path in the config:

`yaml
settings:
claudePath: /custom/path/to/claude
`

$3

If you installed from source, make sure you ran npm link. Check that npm's global bin directory is in your PATH:

`bash
npm bin -g # Should show the directory containing ccode
`

Contributing

Contributions are welcome! This tool was created to solve a real problem and can grow based on community needs.

$3

- Interactive project picker using inquirer or blessed`
- Session history tracking
- Project statistics and analytics
- VS Code extension
- Better error messages
- Test coverage
- Windows native support (non-WSL)

License

MIT

Author

Created to solve the multi-project management problem when working with Claude Code.

Roadmap

- [ ] Publish to npm registry
- [ ] Add interactive project picker
- [ ] Session management and history
- [ ] Parallel task execution
- [ ] Project templates
- [ ] VS Code extension
- [ ] Shell completion (bash/zsh)
- [ ] Configuration validation and linting
- [ ] Project aliases and shortcuts
- [ ] Integration tests

---

Found a bug? Open an issue

Have an idea? Start a discussion