autonomous-claude 1.4.8

Build apps autonomously with Claude Code CLI

autonomous-claude

Build apps autonomously with Claude Code CLI. Uses your existing Claude subscription - no API key required.

Based on Anthropic's long-running agents guide.

Installation

curl -fsSL https://ferdousbhai.com/install.sh | sh

Or download directly from ferdousbhai.com/releases/autonomous-claude.

Prerequisites

Claude Code CLI:

npm install -g @anthropic-ai/claude-code
claude login

GitHub CLI - required for issue tracking:

# Install: https://cli.github.com/
gh auth login

Docker - required for secure sandboxed execution:

# Install Docker: https://docs.docker.com/get-docker/
docker --version  # Verify installation

By default, Claude runs in a Docker container with access only to your project directory. Use --no-sandbox to bypass this isolation (not recommended).

Usage

# cd into your project directory first
cd my-project

# Start a new project or add features
autonomous-claude [INSTRUCTIONS]

# Continue work on existing features
autonomous-claude --continue

Start a new project

# Create and enter project directory
mkdir notes-app && cd notes-app

# With description
autonomous-claude "An Apple Notes clone - local .md storage, folders, rich text, search"

# From a spec file
autonomous-claude ./app-spec.md

Add features to an existing project

cd notes-app

# Add new features
autonomous-claude "Add dark mode and keyboard shortcuts"

Continue work

Continue implementing existing features where you left off:

cd notes-app
autonomous-claude --continue

Options

Option	Short	Description	Default
--continue	-c	Continue work on existing features	-
--no-sandbox	—	Run without Docker sandbox (not recommended)	false
--model	-m	Claude model	Claude Code default
--max-sessions	-n	Max sessions (Claude Code invocations)	100
--timeout	-t	Timeout per session (seconds)	18000 (5 hours)

Configuration

Create ~/.config/autonomous-claude/config.toml to customize defaults:

[session]
timeout = 18000        # Seconds per session (default: 5 hours)
max_turns = 2000       # Max turns per Claude session
max_sessions = 100     # Max Claude sessions before stopping
spec_timeout = 600     # Timeout for spec generation (10 minutes)

[sandbox]
enabled = true         # Run in Docker sandbox (default: true)
memory_limit = "8g"    # Container memory limit
cpu_limit = 4.0        # Container CPU limit

How It Works

New projects

1. Spec Generation: Creates a project specification from your description
2. Session 1 (Initializer): Creates GitHub Issues for each testable feature
3. Sessions 2+ (Coding Agent): Implements features one by one, closing issues when done

Adding features to existing projects

1. Session 1 (Enhancement Initializer): Creates new GitHub Issues for the requested features
2. Sessions 2+ (Coding Agent): Implements the new features

Progress is tracked via GitHub Issues and git commits. Press Ctrl+C to stop, then --continue to resume.

Security

Docker Sandbox (Default)

By default, all Claude Code executions run inside an isolated Docker container.

Mounts:

Host Path	Container Path	Mode	Why
Project directory	/workspace	rw	Code being built
~/.claude/.credentials.json	/home/node/.claude/.credentials.json	rw	Auth tokens (needs write for refresh)
~/.claude/settings.json	/home/node/.claude/settings.json	ro	User preferences
~/.claude/settings.local.json	/home/node/.claude/settings.local.json	ro	Permission allowlists
~/.claude/CLAUDE.md	/home/node/.claude/CLAUDE.md	ro	Personal instructions
~/.claude/skills/	/home/node/.claude/skills/	rw	User-scoped skills (rw for deps/cache)
~/.claude/plugins/	/home/node/.claude/plugins/	ro	Installed plugins
~/.config/gh	/home/node/.config/gh	rw	GitHub CLI auth (rw for token refresh)

Settings and plugins are read-only to prevent a sandboxed session from escalating permissions.

Not accessible: ~/.ssh, ~/.aws, or any directory outside your project.

Limits: 8GB RAM, 4 CPUs (configurable). Runs as non-root with all capabilities dropped.

License

MIT