Skip to content

Commit 3eb1a96

Browse files
deimagjasdeimagjasclaude
authored
docs: add README with dual-mode usage guide and decision flow (#5)
- CI badge and license badge - Two usage modes: direct container vs host skill (spawn-agent) - Mermaid decision flowchart for choosing the right mode - Explains why host skill exists (container feature gaps like /remote-control) - Quick start, project structure, CI reference, documentation links Co-authored-by: deimagjas <deimagjas@127.0.0.1> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 8eb8b18 commit 3eb1a96

1 file changed

Lines changed: 200 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 200 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,200 @@
1+
# stackai
2+
3+
[![CI](https://github.com/deimagjas/stackai/actions/workflows/ci.yml/badge.svg)](https://github.com/deimagjas/stackai/actions/workflows/ci.yml)
4+
[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
5+
6+
Run parallel Claude Code agents in sandboxed Apple Containers with isolated git worktrees.
7+
8+
## What is this?
9+
10+
stackai is an infrastructure toolkit that spawns headless Claude Code instances inside lightweight Linux containers on macOS. Each agent works in its own git worktree, enabling parallel development workflows — multiple agents can work on different branches of the same repository simultaneously.
11+
12+
---
13+
14+
## Two ways to use stackai
15+
16+
stackai provides two distinct usage modes. Both rely on the same container image and infrastructure, but differ in **where the orchestration happens**.
17+
18+
### Mode 1: Direct container usage
19+
20+
Use the Makefile or the `q` CLI to build the image, enter a container interactively, or spawn headless agents directly from your terminal.
21+
22+
**Best for:**
23+
- Running Claude interactively inside the container (full Linux environment with Rust CLI tools)
24+
- Spawning one-off headless agents via `make spawn` or `q spawn`
25+
- Automation scripts and CI-driven agent workflows
26+
- Using Claude features that work reliably inside containers
27+
28+
```bash
29+
# Interactive session inside the container
30+
make run
31+
32+
# Spawn a headless agent
33+
make spawn BRANCH=feat/oauth2 TASK="Implement OAuth2 with JWT tokens"
34+
```
35+
36+
### Mode 2: Host skill (spawn-agent)
37+
38+
Install the `spawn-agent` skill in your host Claude Code session. Claude on your host becomes a **coordinator** that delegates tasks to containerized agents and monitors their progress via `container logs`.
39+
40+
**Best for:**
41+
- Orchestrating multiple agents in parallel from a single Claude conversation
42+
- Tasks that require host-side Claude features not yet available inside containers (e.g., `/remote-control`, MCP servers, IDE integrations)
43+
- Complex workflows where the coordinator needs to review agent output and make decisions before spawning the next agent
44+
45+
```
46+
# From your host Claude Code session:
47+
> spawn an agent on feat/oauth2 to implement OAuth2 with JWT tokens
48+
> spawn another on test/auth to write integration tests for the auth module
49+
> check the status of both agents
50+
```
51+
52+
The skill automatically detects the task type (feature, test, mutation, explore) and builds an appropriate prompt for each agent.
53+
54+
### Why both modes?
55+
56+
Some Claude Code features — such as `/remote-control`, MCP tool connections, and certain IDE integrations — are not yet supported inside containers. The host skill mode lets you keep those capabilities on your host while still delegating compute-heavy coding tasks to isolated container agents. As container support matures, more features will work directly inside the container.
57+
58+
### Decision flow
59+
60+
```mermaid
61+
flowchart TD
62+
A[I want to use stackai] --> B{Do I need host-only\nClaude features?}
63+
64+
B -->|Yes| C{Which features?}
65+
C -->|/remote-control\nMCP servers\nIDE integrations| D[Use host skill mode]
66+
D --> D1["Install spawn-agent skill\nClaude on host coordinates\nagents in containers"]
67+
68+
B -->|No| E{How many agents?}
69+
E -->|One| F{Interactive or headless?}
70+
F -->|Interactive| G["make run\n(enter the container)"]
71+
F -->|Headless| H["make spawn BRANCH=... TASK=...\n(fire and forget)"]
72+
73+
E -->|Multiple in parallel| I{Do I need coordination\nbetween agents?}
74+
I -->|Yes| D
75+
I -->|No| J["Run multiple make spawn\ncommands in parallel"]
76+
```
77+
78+
---
79+
80+
## Key components
81+
82+
| Component | Path | Description |
83+
|---|---|---|
84+
| Container image | `config/Dockerfile.wolfi` | ARM64 Wolfi-based image with Claude Code, Rust CLI tools, and Node/Python runtimes |
85+
| Entrypoint | `config/entrypoint.sh` | Credential injection, worktree creation, headless agent launch |
86+
| Makefile | `config/Makefile` | Build, spawn, monitor, and stop agents |
87+
| CLI (`q`) | `app/cli/` | Python CLI (Typer) wrapping Makefile targets |
88+
| Spawn skill | `docs/agents/spawn-agent-skill.md` | Host-side Claude Code skill for multi-agent coordination |
89+
| Docs | `docs/agents/` | Architecture, setup, spawn skill, evals |
90+
91+
## Requirements
92+
93+
- macOS 26+ (Sequoia) with Apple Container CLI
94+
- Apple Silicon (ARM64)
95+
- Claude Pro or Max subscription ([claude.ai](https://claude.ai))
96+
- Python 3.13+ and [uv](https://docs.astral.sh/uv/)
97+
- Git
98+
99+
## Quick start
100+
101+
### 1. Build the image
102+
103+
```bash
104+
cd config
105+
make build
106+
```
107+
108+
### 2. Set up authentication
109+
110+
```bash
111+
claude login # authenticate via browser OAuth
112+
claude setup-token # generates the container token
113+
export CLAUDE_CONTAINER_OAUTH_TOKEN=<token>
114+
```
115+
116+
See [docs/agents/setup.md](docs/agents/setup.md) for the full dual-token architecture explanation.
117+
118+
### 3. Create the network
119+
120+
```bash
121+
make network
122+
```
123+
124+
### 4. Spawn an agent
125+
126+
```bash
127+
make spawn BRANCH=feat/oauth2 TASK="Implement OAuth2 with JWT tokens"
128+
```
129+
130+
Or using the CLI:
131+
132+
```bash
133+
cd app/cli && uv sync
134+
q spawn --branch feat/oauth2 --task "Implement OAuth2 with JWT tokens"
135+
```
136+
137+
### 5. Monitor
138+
139+
```bash
140+
make list-agents # active containers and worktrees
141+
make follow-agent BRANCH=feat/oauth2 # stream logs
142+
make stop-agent BRANCH=feat/oauth2 # stop when done
143+
```
144+
145+
## Project structure
146+
147+
```
148+
stackai/
149+
├── app/
150+
│ ├── cli/ # Python CLI (q command)
151+
│ └── agents-templates/ # Agent template examples
152+
├── config/
153+
│ ├── Dockerfile.wolfi # Production image (ARM64, glibc)
154+
│ ├── Dockerfile # CI image (Alpine, amd64)
155+
│ ├── Makefile # Build/spawn/monitor targets
156+
│ ├── entrypoint.sh # Container entrypoint
157+
│ └── spec/ # ShellSpec BDD tests
158+
├── docs/agents/
159+
│ ├── container-agent.md # Image and Makefile reference
160+
│ ├── spawn-agent-skill.md # Spawn skill architecture
161+
│ ├── setup.md # Authentication guide
162+
│ ├── evals.md # Evaluation framework
163+
│ └── cli.md # CLI command reference
164+
├── iac/ # Infrastructure as Code
165+
└── model/ # ML fine-tuning experiments
166+
```
167+
168+
## How it works
169+
170+
1. **Build** — `Dockerfile.wolfi` compiles Rust CLI tools (ripgrep, fd, bat, eza, dust, procs, bottom) in a builder stage, then installs Claude Code CLI, Node.js, Python, and GitHub CLI in the runtime stage.
171+
172+
2. **Spawn** — The Makefile creates a git worktree for the target branch, launches a container with read-only credential mounts, and runs `claude --dangerously-skip-permissions -p "<task>"` as a non-root user via `su-exec`.
173+
174+
3. **Isolate** — Each container gets its own worktree under `$AGENTS_HOME`, its own credential copy, and its own `CLAUDE_CODE_OAUTH_TOKEN`. The host credentials are never modified.
175+
176+
4. **Merge** — When the agent finishes, its branch is ready for review and merge via standard git workflow.
177+
178+
## CI
179+
180+
GitHub Actions runs on every push to `main` and on pull requests:
181+
182+
| Job | What it checks |
183+
|---|---|
184+
| `lint` | ruff on `app/cli/` |
185+
| `test-cli` | pytest for the Python CLI |
186+
| `test-entrypoint` | ShellSpec BDD tests for `entrypoint.sh` |
187+
| `dockerfile-lint` | hadolint on both Dockerfiles |
188+
| `docker-build` | Alpine builder stage compilation |
189+
190+
## Documentation
191+
192+
- [Container image and Makefile](docs/agents/container-agent.md)
193+
- [Setup and authentication](docs/agents/setup.md)
194+
- [Spawn agent skill](docs/agents/spawn-agent-skill.md)
195+
- [CLI reference](docs/agents/cli.md)
196+
- [Evals](docs/agents/evals.md)
197+
198+
## License
199+
200+
[Apache 2.0](LICENSE)

0 commit comments

Comments
 (0)