autoclaude-cli
Local runner for AutoClaude. Executes orchestration plans handed down from the server using your own Claude Max/Pro subscription. The server never pays for tokens.
AutoClaude turns Claude Code into an always-on teammate. Schedule plans, ship work overnight, and track costs from one dashboard. Sign up at autoclaude.grezy.org.
Requirements
- Python 3.11+
- Claude Code CLI on
$PATH(claude --versionworks) and a Max or Pro subscription signed in. ghCLI signed in with access to the target repo.- Git.
Install
With uv (recommended):
uv tool install autoclaude-cli
Or with pipx:
pipx install autoclaude-cli
Don't have uv yet? Install it first:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS / Linux
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" # Windows
During development, install from source:
uv tool install --force . # or: pipx install --force ./
Quickstart
# 1. Authenticate once. Defaults to https://autoclaude.grezy.org.
# Login also installs two per-user services:
# - heartbeat (always-on liveness ping; never paused)
# - scheduler (runs `autoclaude tick` every 5 minutes)
autoclaude login
# 2. Verify everything is wired up.
autoclaude diag
autoclaude services # heartbeat + scheduler status
# 3. Fire a tick manually if you don't want to wait for the scheduler.
autoclaude tick
Pause / resume / switch server
autoclaude pause # stop scheduled ticks (heartbeat keeps running)
autoclaude play # resume scheduled ticks
autoclaude switch staging # change active profile and rebind both services
pause only stops the scheduler. The heartbeat is always on so the
dashboard's "Active CLIs" KPI stays accurate.
Profiles
autoclaude supports multiple named profiles (stored in ~/.config/autoclaude/config.toml). Each profile holds one URL, its API key, and an optional repo checkout.
autoclaude login # default profile -> prod
autoclaude --profile staging login --url https://stage.example.com
autoclaude --profile staging tick
AUTOCLAUDE_PROFILE=staging autoclaude tick
List configured profiles and switch the active one persistently:
autoclaude profiles # list profiles, * marks active
autoclaude use staging # set active profile (persists in config.toml)
--url accepts localhost:3001 (http is assumed) or a full https://… URL. Override at runtime with AUTOCLAUDE_URL / AUTOCLAUDE_API_KEY.
How it works
- CLI mirrors the source repo into
$AUTOCLAUDE_HOME/repos/<slug>/(defaults to~/.autoclaude/repos/<slug>/); subsequent ticks just fetch. - CLI fetches the current plan from
GET /api/ac/runner/context/. - After opening the tick, CLI creates a dedicated git worktree at
$AUTOCLAUDE_HOME/worktrees/<slug>/<tick_id>/on branchautoclaude/<slug>/tick-<tick_id>. - For each step in the plan:
- Spawns
claude -p "<prompt>"inside the worktree. The user's checkout is never modified.
- Spawns
- Closes the tick with the outcome and cost report, removes the worktree, and keeps the branch so the changes remain inspectable.
Override the workspace root with the AUTOCLAUDE_HOME environment variable.
Running as root
The claude CLI refuses to combine --permission-mode bypassPermissions (or
--dangerously-skip-permissions) with an effective UID of 0. autoclaude detects
this case automatically and:
- Creates a system group and user named
autoclaude(idempotent), and addsrootto theautoclaudegroup so both accounts can share files. - Symlinks
/home/autoclaude/.claudeto root's~/.claudeso the spawned process reuses the same authentication and settings. - Grants the
autoclaudegroup rwX on the working repo. - Wraps the
claudeinvocation withrunuser -u autoclaude --preserve-environment --(falling back tosudo -E -u autoclaudeifrunuseris unavailable).
If neither useradd/adduser nor runuser/sudo are present (e.g. minimal
busybox containers), autoclaude fails the step with a clear message pointing
at https://github.com/grezy-software/autoclaude-cli/issues so we can extend
support for that platform.
Permission mode auto-detection
If your ~/.claude/settings.json (or the project-level
<repo>/.claude/settings.json, which takes precedence) already has:
{ "permissions": { "defaultMode": "auto" } }
then autoclaude will spawn claude without the --permission-mode flag and
let claude's auto mode handle permissions itself. Otherwise it keeps passing
--permission-mode bypassPermissions as before.
License
MIT. See LICENSE.
1 maintainer
Metadata
1 maintainer
Release files for autoclaude-cli 2.8.5
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| autoclaude_cli-2.8.5.tar.gz | 166.3 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| autoclaude_cli-2.8.5-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 280.8 kB
Release files / autoclaude_cli-2.8.5.tar.gz
| Download URL | autoclaude_cli-2.8.5.tar.gz |
|---|---|
| Size | 166.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
14d7640386da6c195762298bfd9482b58182a157fe370f9269963848b98d66f5
|
|
BLAKE2b-256 checksum How to use checksums |
3043602e7c5ba89fc247ea87cbc96f1b027fa7599e34347c2ae33cc53e64d347
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 7, 2026.
Transparency logRelease files / autoclaude_cli-2.8.5-py3-none-any.whl
| Download URL | autoclaude_cli-2.8.5-py3-none-any.whl |
|---|---|
| Size | 114.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
a9582efbd6a42f1bd2db0c9baaf54f4450292e3d6cf00d1bab3c7bbb45932bb9
|
|
BLAKE2b-256 checksum How to use checksums |
0f11e853f8d614555a6d9ab54151953ff8e70109b27be2862e844c0a2b9c5d1e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
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 May 7, 2026.
Transparency log
