sandman

README

Sandman

Sleep while your agents code.

AFK coding agents orchestration in isolated sandboxes.

Quick Start

# Prerequisites: Git, gh and OpenCode properly configured

# 1. Initialize a project
cd my-repo && sandman init

# 2. Run the review daemon (optional)
sandman review

# 3. Open the browser portal (optional)
sandman portal

# 4. Implement your GitHub issues AFK
sandman run 42 43

Overview

Sandman manages the lifecycle of automated coding workflows:

• Fetches GitHub issues via the gh CLI
• Renders prompt templates for AI coding agents
• Creates isolated sandboxes (git worktrees or containers)
• Orchestrates parallel agent execution with dependency-aware scheduling
• Logs structured events for observability
• Serves a local portal for watching current repo runs in the browser (binds to 127.0.0.1 by default; use --host 0.0.0.0 or SANDMAN_PORTAL_HOST=0.0.0.0 to expose on all interfaces)

Documentation

Guide	Description
Overview	What Sandman is, the delivery loop, and what it is not
Quick Start	The five-minute path from install to first run
Installation	Prerequisites, installation, OpenCode setup, and project setup
Concepts	The Batch / AgentRun / Sandbox / Specification model in prose
Commands Reference	All CLI commands, flags, and issue selection modes
Scaffolding and Supported Languages	sandman init, generated files, build-tool presets, and language version selection
Configuration	Full config schema, default agent, and CLI config
Workflows	Running agents, dependency-aware execution, continue and cleanup
Sandbox Modes	Worktree vs container-backed sandboxing
Portal	Local browser dashboard for repo-scoped Sandman runs
Reviews	Review daemon and review-run output
Default Task Prompt	Bootstrap task prompt, lifecycle, and task file
Skills	Shared Sandman skill installation and workflow
Badge	Built with Sandman badge — trigger, idempotency, and opt-out
Monitoring and Debugging	Status, history, event log, and idle timeout
Troubleshooting	Common failure modes and the first thing to try for each
Agent Compatibility	Built-in agent presets and container auth model
FAQ	Questions people ask before installing

Other:

• Architecture Overview and Disk Layout
• Positioning — what Sandman is and isn't, in plain language
• Development docs — contributor setup, project structure, architecture guidance, testing, and the Documentation page covering docs and embedded-skill rules

Development

Contributing to Sandman? See the Development docs.

License

MIT