autonomous-claude 0.8.0

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

# Install uv if you haven't
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install autonomous-claude
uv tool install autonomous-claude

Or install from source:

git clone https://github.com/ferdousbhai/autonomous-claude.git
cd autonomous-claude
uv tool install .

Prerequisites

Claude Code CLI must be installed and authenticated:

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

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

# Update to latest version
autonomous-claude update

Start a new project

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

# Interactive - prompts for description
autonomous-claude

# 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"

Note: If your project has incomplete features, you'll be asked to confirm. Use --continue to resume without adding new features.

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	-
--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)
--verbose	—	Stream Claude output in real-time	false

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)

[tools]
allowed = ["Read", "Write", "Edit", "MultiEdit", "Glob", "Grep", "Bash", "WebSearch", "WebFetch"]

[ui]
pending_display_limit = 10     # Max pending features to show

Spec Confirmation

Before building, Claude generates a detailed spec from your description. You can review and request changes:

Accept? [y] n
What needs changing? Add offline support and keyboard shortcuts
Updating spec...

Type y (or press Enter) to accept, or describe what to change.

Project Files

The tool creates these files in your project:

File	Purpose
feature_list.json	Tracks features and their completion status
app_spec.txt	The full application specification
claude-progress.txt	Session notes and progress updates
.autonomous-claude/logs/	Session logs (stdout, stderr, prompts)

Use --verbose to stream Claude's output in real-time instead of showing a spinner.

How It Works

New projects

1. Session 1 (Initializer): Creates feature_list.json with testable features
2. Sessions 2+ (Coding Agent): Implements features one by one, marking them as passing

Adding features to existing projects

1. Session 1 (Enhancement Initializer): Appends new features to existing feature_list.json
2. Sessions 2+ (Coding Agent): Implements the new features

Progress is persisted via feature_list.json and git commits. Press Ctrl+C to stop, then --continue to resume.

Example

$ mkdir apple-notes-clone && cd apple-notes-clone
$ autonomous-claude "An Apple Notes clone - web app with local .md file storage, folder organization, rich text editing, and full-text search"

╔═╗╦ ╦╔╦╗╔═╗╔╗╔╔═╗╔╦╗╔═╗╦ ╦╔═╗
╠═╣║ ║ ║ ║ ║║║║║ ║║║║║ ║║ ║╚═╗
╩ ╩╚═╝ ╩ ╚═╝╝╚╝╚═╝╩ ╩╚═╝╚═╝╚═╝
     Claude Code CLI

  Project     /home/user/apple-notes-clone
  Model       Claude Code default

Starting new project - initializer will run first
...

Security Note

This tool uses --dangerously-skip-permissions for autonomous operation. Only run in trusted environments.

License

MIT - Based on Anthropic's claude-quickstarts