You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
docs: expand CLAUDE.md and fix container memory to 3G (#6)
* docs: add README with dual-mode usage guide and decision flow
- 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: Claude Opus 4.6 <noreply@anthropic.com>
* docs: expand CLAUDE.md with build/test/architecture guide and fix memory to 3G
Add build commands, test instructions, architecture overview, and key
concepts to CLAUDE.md so future Claude Code instances can be productive
immediately. Also correct container memory allocation from 12G to 3G
across Makefile, skill, and docs to match actual resource requirements.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---------
Co-authored-by: deimagjas <deimagjas@127.0.0.1>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: CLAUDE.md
+82Lines changed: 82 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,77 @@
1
1
# CLAUDE.md
2
2
3
+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4
+
5
+
## Overview
6
+
7
+
stackai orchestrates parallel Claude Code agents in sandboxed Apple Containers (macOS 26+, ARM64). Each agent runs in its own git worktree for branch-isolated development. Two modes: direct container management (Makefile/CLI) and host-side skill coordination (spawn-agent).
8
+
9
+
## Build & run
10
+
11
+
```bash
12
+
# Build the production image (ARM64, Wolfi-based)
13
+
cd config && make build
14
+
15
+
# Create the container network (required once)
16
+
make network
17
+
18
+
# Interactive container session
19
+
make run
20
+
21
+
# Spawn a headless agent
22
+
make spawn BRANCH=feat/foo TASK="implement feature X"
23
+
24
+
# Monitor agents
25
+
make list-agents
26
+
make follow-agent BRANCH=feat/foo
27
+
make stop-agent BRANCH=feat/foo
28
+
29
+
# Cleanup
30
+
make clean # remove image + containers
31
+
make clean-network # remove bridge network
32
+
make clean-all # remove everything
33
+
```
34
+
35
+
### Python CLI (`q` command)
36
+
37
+
```bash
38
+
cd app/cli && uv sync
39
+
uv run q build
40
+
uv run q spawn --branch feat/foo --task "implement feature X"
41
+
uv run q agents list
42
+
```
43
+
44
+
## Testing
45
+
46
+
```bash
47
+
# Python CLI tests (from app/cli/)
48
+
cd app/cli && uv sync
49
+
uv run pytest -v # full suite
50
+
uv run pytest tests/test_agents.py # single module
51
+
uv run pytest -k test_spawn # single test by name
52
+
53
+
# Linting
54
+
uv run ruff check .
55
+
56
+
# Entrypoint BDD tests (from config/)
57
+
cd config && shellspec --shell bash
58
+
```
59
+
60
+
CI runs all of these plus hadolint on both Dockerfiles and an Alpine builder stage compilation check.
-**`app/cli/`** — Python CLI (`q`) using Typer+Rich that wraps Makefile targets. Entry point registered as `q` in pyproject.toml. Commands delegate to `make` via `utils.run_make()`
66
+
-**`.claude/skills/`** — Host-side Claude Code skills for multi-agent orchestration (spawn-agent, spawn-agent-workspace)
-**Dual-token architecture**: Host uses `CLAUDE_CONTAINER_OAUTH_TOKEN`; inside the container it maps to `CLAUDE_CODE_OAUTH_TOKEN`. Host credentials are mounted read-only and copied (never modified in place).
72
+
-**Worktree isolation**: Each agent gets its own git worktree under `$AGENTS_HOME` (default: sibling `.worktrees/` directory). Branches are merge-ready when the agent finishes.
73
+
-**Apple Container CLI**: This project uses Apple's container runtime, not Docker. The Makefile targets use `container` commands.
74
+
3
75
## Documentation
4
76
5
77
When implementing a new feature, always update the relevant documentation in `docs/`.
@@ -10,3 +82,13 @@ When implementing a new feature, always update the relevant documentation in `do
10
82
- If a new subsystem is introduced with no existing doc, create a new file under the appropriate `docs/` subdirectory
11
83
12
84
Documentation should reflect the current state of the code. Keep troubleshooting tables and flow descriptions in sync with the actual implementation.
85
+
86
+
## Skill evals
87
+
88
+
When modifying any skill under `.claude/skills/`, run its evals locally before considering the change complete. Evals verify that the skill still produces correct outputs across all test scenarios.
89
+
90
+
```
91
+
/skill-creator:skill-creator run evals for the <skill-name> skill at ~/.claude/skills/<skill-name>/
92
+
```
93
+
94
+
See `docs/agents/evals.md` for full details on prerequisites, how to add new evals, and how to interpret results.
0 commit comments