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-sandboxto 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
- Spec Generation: Creates a project specification from your description
- Session 1 (Initializer): Creates GitHub Issues for each testable feature
- Sessions 2+ (Coding Agent): Implements features one by one, closing issues when done
Adding features to existing projects
- Session 1 (Enhancement Initializer): Creates new GitHub Issues for the requested features
- 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
1 maintainer
Metadata
1 maintainer
Release files for autonomous-claude 1.4.8
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| autonomous_claude-1.4.8.tar.gz | 26.2 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| autonomous_claude-1.4.8-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 46.4 kB
Release files / autonomous_claude-1.4.8.tar.gz
| Download URL | autonomous_claude-1.4.8.tar.gz |
|---|---|
| Size | 26.2 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d359a95ddcc1e4350800c33a6b56a9a2f3fd60ab66c3df073b618b37c302b24e
|
|
BLAKE2b-256 checksum How to use checksums |
8a05023ee108502b935dd71d4f0bbb6a3a57f72b5c44c8b83a31a67225737eb7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 7, 2026.
Transparency logRelease files / autonomous_claude-1.4.8-py3-none-any.whl
| Download URL | autonomous_claude-1.4.8-py3-none-any.whl |
|---|---|
| Size | 20.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cbbde3d7a17fdb4840865a0981748afea546769e73bb5549167f469040eeb35b
|
|
BLAKE2b-256 checksum How to use checksums |
466181c406c550fab1f96f065c39b5dd48388269be532c62681c57f171a77b8a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.7
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 7, 2026.
Transparency logSecurity for autonomous-claude 1.4.8
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for autonomous_claude-1.4.8.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Jan 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
