Principles

The thinking behind this tool.

Guiding Philosophies

Just shells

Run multiple Claude Codes via SSH. No orchestration framework. No agent library. Just terminals you coordinate from one place.

Secrets belong to skills

Credentials attach to skills, not floating in environment. When a skill runs, its secrets inject. Clear lineage—you know exactly what credentials a skill needs before you run it.

Your skills, your way

Everyone deploys differently. Everyone commits differently. Define common tasks in SKILL.md, reuse everywhere. Global skills or per-project—you decide.

SKILL.md Format

Skills are defined in markdown. Readable, versionable, portable.

# Deploy

## Description
Build and deploy to production.

## Prompt
Run the test suite. If all tests pass, build the project
and deploy to the production server. Report the URL when done.

## Secrets
- DEPLOY_KEY: SSH key for production server
- SLACK_WEBHOOK: For deployment notifications

Sections:

# Name — Skill name (required)

## Description — What this skill does

## Prompt — The prompt sent to Claude Code

## Secrets — Credentials needed, as - NAME: description

Skill Scope

Skills can be global (available everywhere) or per-folder (project-specific).

~/.skills/ # Global skills ├── deploy.md ├── commit.md └── review.md ./skills/ # Per-project skills ├── deploy.md # Overrides global └── seed-db.md

Per-folder skills override global skills with the same name.

Why This Approach

No framework. Tools like Claude Colony and claude-flow add useful features, but also complexity. This tool has one opinion: run Claude Code in terminals and let you coordinate them. Use tmux, worktrees, containers—whatever you prefer.

Secrets on-demand. When you run a skill that needs credentials, you're prompted. Secrets don't live in config files. Clear when they're used, never persisted.

Status visible. Classic HIG principle: never hide state. If an agent is running, you see it. If a skill needs secrets, you know before it runs.

User trust. You categorize your own agents. You write your own skills. The tool doesn't impose taxonomy or opinionated workflows.

Backend Architecture

The orchestrator connects to machines running Claude Code over SSH.

Network. Two supported options:

Tailscale # For machines anywhere. Install, done. Direct IP # For machines on your local network.

Tailscale is the answer for most setups. Install on each machine, they find each other automatically. Use the Tailscale IP or MagicDNS hostname (like macbook.tail1234.ts.net) when adding agents.

SSH setup. Each machine needs:

# On each target machine
1. SSH server running (sshd)
2. Your public key in ~/.ssh/authorized_keys
3. Claude Code installed (npm i -g @anthropic-ai/claude-code)

Session management. When you add an agent, the orchestrator:

# What happens under the hood
ssh user@host                     # Connect
cd ~/project && claude           # Start Claude Code
# Session stays open, input/output streamed

Each pane is one SSH connection, one Claude Code process. Close the pane, connection ends. Simple.

Session persistence. For long-running agents, use tmux or screen on the remote:

# On remote machine
tmux new -s agent1
claude

# Later, reconnect
tmux attach -t agent1

The orchestrator can attach to existing tmux sessions instead of starting fresh Claude Code instances.

API keys. Claude Code on each machine needs its own ANTHROPIC_API_KEY. Set it in the remote machine's environment, not passed through the orchestrator. Your API key never leaves the machine it runs on.

Making It Real

The UI is a demo—it simulates Claude Code responses in the browser. To connect to real machines, run the WebSocket server.

Architecture:

# Browser can't SSH directly (security)
# So we bridge through a small server

Browser ←WebSocket→ server.js ←SSH→ Remote
                         ↑
                    runs on your
                    laptop/pi/server

Setup:

# Clone and run the server
cd projects/agent-orchestrator-demo
npm install ws ssh2
node server.js

# Then tap DEMO badge in UI to switch to SSH

The server handles:

• connect — SSH to remote, start claude CLI

• input — Send your text to Claude Code

• disconnect — Close SSH session

See server.js for full implementation. Uses ssh2 npm package.

Example Skills

# Commit

## Prompt
Review git diff. Stage all changes. Write a descriptive
commit message based on what changed. Do not push.

# Review

## Prompt
Review staged changes. Look for bugs, security issues,
code style problems. Be specific about line numbers.

# Test

## Prompt
Run the test suite. If any fail, analyze failures and
suggest fixes. If all pass, report success.