https://github.com/ourines/codes
Codes CLI - Manage multiple Claude Code configurations with ease. Switch between different Claude API endpoints (official, proxies, alternative providers), handle authentication tokens, and streamline your AI-powered development workflow.
https://github.com/ourines/codes
ai api-management claude claude-code configuration-management golang multi-config
Last synced: 4 months ago
JSON representation
Codes CLI - Manage multiple Claude Code configurations with ease. Switch between different Claude API endpoints (official, proxies, alternative providers), handle authentication tokens, and streamline your AI-powered development workflow.
- Host: GitHub
- URL: https://github.com/ourines/codes
- Owner: ourines
- License: mit
- Created: 2025-10-11T01:46:28.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2026-02-13T16:41:28.000Z (4 months ago)
- Last Synced: 2026-02-14T00:52:03.586Z (4 months ago)
- Topics: ai, api-management, claude, claude-code, configuration-management, golang, multi-config
- Language: Go
- Homepage:
- Size: 6.47 MB
- Stars: 8
- Watchers: 0
- Forks: 1
- Open Issues: 5
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Codes CLI
[English](README.md) | [中文](README.zh-CN.md)
Environment configuration management, project management, and multi-agent collaboration tool for Claude Code. Switch API profiles instantly, manage project workspaces, and orchestrate autonomous agent teams to tackle complex tasks in parallel.
## Features
- **Profile Switching** — Manage multiple API configurations (Anthropic, proxies, custom endpoints) and switch instantly
- **Project Management** — Project aliases, workspace management, interactive TUI
- **Agent Teams** — Autonomous Claude agents collaborating with task dependencies, messaging, and auto-reporting
- **Workflow Templates** — YAML-based agent team templates for repeatable multi-agent pipelines
- **Cost Tracking** — Session-level API usage statistics by project and model
- **MCP Server** — 40 tools integrated into Claude Code for managing everything from conversations
- **Cross-Platform** — Linux, macOS, Windows (amd64 & arm64)
## Install
```bash
# Linux / macOS
curl -fsSL https://raw.githubusercontent.com/ourines/codes/main/install.sh | sh
# Windows (PowerShell)
irm https://raw.githubusercontent.com/ourines/codes/main/install.ps1 | iex
# From source (Go 1.24+)
git clone https://github.com/ourines/codes.git && cd codes && make build
```
Then run `codes init` to set up shell completion and PATH.
## Claude Code Integration
Add `codes` as an MCP server to let Claude Code manage agent teams, projects, and profiles directly.
**Project-level** (`.mcp.json` in project root):
```json
{
"mcpServers": {
"codes": {
"command": "codes",
"args": ["serve"]
}
}
}
```
**User-level** (`~/.claude/claude_code_config.json`):
```json
{
"mcpServers": {
"codes": {
"command": "codes",
"args": ["serve"]
}
}
}
```
Once configured, Claude Code gains access to 39 MCP tools:
| Category | Tools | Examples |
|----------|-------|---------|
| **Config** (10) | Projects, profiles, remotes | `list_projects`, `switch_profile`, `sync_remote` |
| **Agent** (21) | Teams, tasks, messages | `team_create`, `task_create`, `message_send` |
| **Stats** (4) | Usage tracking | `stats_summary`, `stats_by_project`, `stats_by_model` |
| **Workflow** (4) | Templates | `workflow_list`, `workflow_run`, `workflow_create` |
Usage in Claude Code:
```
You: Create a team to refactor the auth module
Claude: I'll set up a team with a coder and tester...
[uses team_create, agent_add, task_create tools]
You: What's the status?
Claude: [uses team_status tool]
The coder completed 2/3 tasks. Tester is waiting on task #3.
```
## Quick Start: Agent Teams
```bash
# Create a team with agents
codes agent team create myteam --workdir ~/Projects/myproject
codes agent add myteam coder --role "implementation" --model sonnet
codes agent add myteam tester --role "testing" --model sonnet
# Start agents and create tasks
codes agent start-all myteam
codes agent task create myteam "Implement login API" --assign coder --priority high
codes agent task create myteam "Write login tests" --assign tester --blocked-by 1
# Monitor and clean up
codes agent status myteam
codes agent stop-all myteam
```
### How It Works
Agents run as independent daemon processes, polling a shared file-based task queue every 3 seconds. Each agent executes tasks by spawning Claude CLI subprocesses and auto-reports results to the team.
All state lives in `~/.codes/teams//` as JSON files — no databases, no message brokers. Filesystem atomic renames guarantee safe concurrent access.
## Workflow Templates
Workflows are reusable YAML templates that define agent teams and tasks. Running a workflow creates a team, starts agents, and queues tasks — all in one command.
```bash
# List available workflows
codes workflow list
# Run a built-in workflow
codes workflow run pre-pr-check
# Create your own
codes workflow create my-pipeline
```
Example workflow YAML (`~/.codes/workflows/my-pipeline.yml`):
```yaml
name: my-pipeline
description: Build, test, and review
agents:
- name: builder
role: Build and compile the project
- name: tester
role: Run tests and report failures
- name: reviewer
role: Review code quality
tasks:
- subject: Build project
assign: builder
prompt: Run the build and fix any compilation errors
- subject: Run tests
assign: tester
prompt: Execute the test suite and report results
blocked_by: [1]
- subject: Code review
assign: reviewer
prompt: Review recent changes for quality issues
blocked_by: [1]
```
Workflows can also be created programmatically via the `workflow_create` MCP tool.
## Commands
```
codes # Launch TUI (when TTY detected)
codes init [--yes] # Install binary + shell completion
codes start # Launch Claude in directory (alias: s)
codes version / update # Version info / update Claude CLI
codes doctor # System diagnostics
```
### Profile Management (`codes profile`, alias: `pf`)
```bash
codes profile add # Add new profile interactively
codes profile select # Switch active profile
codes profile test [name] # Test connectivity
codes profile list / remove
```
### Project Aliases (`codes project`, alias: `p`)
```bash
codes project add [name] [path] # Add project alias
codes project list / remove
```
### Configuration (`codes config`, alias: `c`)
```bash
codes config get [key] # Show settings
codes config set # Set value
codes config list # List available values
codes config reset [key] # Reset to default
codes config export / import # Export/import configuration
```
| Key | Values | Description |
|-----|--------|-------------|
| `default-behavior` | `current`, `last`, `home` | Startup directory |
| `skip-permissions` | `true`, `false` | Skip permission prompts |
| `terminal` | `terminal`, `iterm`, `warp` | Terminal emulator |
### Agent Teams (`codes agent`, alias: `a`)
```bash
# Teams
codes agent team create [--workdir ] [--description ]
codes agent team list / info / delete
codes agent status # Team dashboard
# Agents
codes agent add [--role ] [--model ] [--type worker|leader]
codes agent remove
codes agent start|stop
codes agent start-all|stop-all
# Tasks
codes agent task create [--assign ] [--priority high|normal|low] [--blocked-by ]
codes agent task list [--status ] [--owner ]
codes agent task get / cancel
# Messages
codes agent message send --from [--to ]
codes agent message list --agent
```
### Workflow Templates (`codes workflow`, alias: `wf`)
```bash
codes workflow list # List all workflows
codes workflow run [-d ] [-m ] [-p ]
codes workflow create # Create template
codes workflow delete
```
### Cost Tracking (`codes stats`, alias: `st`)
```bash
codes stats summary [period] # Cost summary (today/week/month/all)
codes stats project [name] # Cost by project
codes stats model # Cost by model
codes stats refresh # Force cache rebuild
```
### Remote Hosts (`codes remote`, alias: `r`)
```bash
codes remote add
codes remote list / status
codes remote setup / ssh
```
## Configuration
Config file location: `~/.codes/config.json` (fallback: `./config.json`)
```json
{
"profiles": [
{
"name": "work",
"env": {
"ANTHROPIC_BASE_URL": "https://api.anthropic.com",
"ANTHROPIC_AUTH_TOKEN": "sk-ant-xxxxx"
}
}
],
"default": "work",
"defaultBehavior": "current",
"terminal": "terminal",
"projects": { "my-project": "/path/to/project" }
}
```
Supported environment variables
| Variable | Description |
|----------|-------------|
| `ANTHROPIC_BASE_URL` | API endpoint URL |
| `ANTHROPIC_AUTH_TOKEN` | Authentication token |
| `ANTHROPIC_API_KEY` | API key (alternative auth) |
| `ANTHROPIC_MODEL` | Default model |
| `ANTHROPIC_DEFAULT_HAIKU_MODEL` | Haiku model override |
| `ANTHROPIC_DEFAULT_SONNET_MODEL` | Sonnet model override |
| `ANTHROPIC_DEFAULT_OPUS_MODEL` | Opus model override |
| `MAX_THINKING_TOKENS` | Maximum thinking tokens |
| `HTTP_PROXY` / `HTTPS_PROXY` | Proxy settings |
## Development
```
codes/
├── cmd/codes/ # Entry point
├── internal/
│ ├── agent/ # Agent teams: daemon, runner, storage
│ ├── commands/ # Cobra CLI commands
│ ├── config/ # Configuration management
│ ├── mcp/ # MCP server (40 tools, stdio transport)
│ ├── session/ # Terminal session manager
│ ├── stats/ # Cost tracking and aggregation
│ ├── remote/ # SSH remote management
│ ├── tui/ # Interactive TUI (bubbletea)
│ ├── ui/ # CLI output helpers
│ └── workflow/ # Workflow templates and orchestration
└── .github/workflows/ # CI/CD
```
```bash
make build # Build binary
make test # Run tests
go vet ./... # Lint
```
## License
[MIT License](LICENSE)