autorunne 0.6.1

Local-first agent development workspace that turns any repo into an Autorunne project.

Autorunne

Turn any Git repository into a durable AI coding workspace for Claude Code, Codex, Gemini, Hermes, Cursor, and GitHub Copilot.

Autorunne is a local-first workflow CLI for people already building with coding agents but who are tired of losing project state between sessions.

It gives every repo a shared workflow core:

• project context
• tasks
• decisions
• session history
• next action
• agent-ready entry docs

At the same time, it keeps .autorunne/ out of the formal release version.

Why it is different

Most AI coding tools help write code once.

Autorunne is built for the harder problem:

• resuming work tomorrow without re-explaining the repo
• handing the same repo across Claude Code, Codex, Gemini, Hermes, Cursor, or GitHub Copilot
• keeping project memory local instead of trapped in one chat window
• finishing work cleanly with start → checkpoint → finish
• separating internal AI workflow state from the shipped product

Best fit

• solo builders shipping client work
• developers using multiple coding-agent tools
• teams that want a simple repo-local memory layer, not a heavy AI platform

Not trying to be

• a replacement IDE
• a giant autonomous-agent platform
• a chat wrapper with no durable project state

Documentation

• 中文操作手册（新手安装与使用）
• 中文使用说明
• English usage guide
• Autorunne 与大模型开发对接说明
• Autorunne 自动识别 / 自动初始化 / 自动恢复
• Autorunne 发布与合并策略
• Autorunne 产品说明书
• Autorunne 商业计划书
• Autorunne 对外定位与销售话术

---

What problem it solves

Most AI coding tools can edit code, but they are weak at:

• resuming cleanly tomorrow
• carrying project memory across sessions
• working safely inside cloned open-source repos
• separating private workflow state from public release output
• staying useful across editors instead of being locked into one IDE

Autorunne solves this by acting as a workflow layer, not just another chat wrapper.

---

Product principles

This project is built around four product directions:

1. Installation system

   • behaves like a real developer CLI
   • ships release assets
   • is ready for pipx / PyPI style distribution

2. Stronger project detection

   • understands common stacks, workspace layouts, and build systems
   • gives agents immediate context in existing repos

3. Unified workflow core layer

   • the workflow lives in .autorunne/
   • agents plug into that shared context instead of inventing their own memory format

4. Editors are entry points, not the core

   • VS Code can auto-open and auto-bootstrap on folder open
   • the CLI remains the source of truth
   • this makes future support for other editors easier

---

Current version

0.6.1

New in 0.6.1

• adds a clearer public install flow with scripts/install.sh
• adds pinned public release-wheel install support
• adds daemon --max-syncs so the loop can stop after the first meaningful auto-sync
• adds changed-file reporting in daemon output
• adds a GitHub-visible Chinese operator manual for installation and daily use
• clarifies the real workflow: install Autorunne once, initialize each repo once, then launch Codex / Claude Code directly from the repo terminal

Previously added in 0.3.0

• autorunne release
• autorunne completion
• autorunne hooks --with-pre-commit
• stronger autorunne doctor
• monorepo / workspace / Turborepo detection

---

Supported project types today

Web / app / service stacks

• npm / pnpm / yarn / bun
• React
• Next.js
• Vite
• Vue
• Nuxt
• Svelte / SvelteKit
• Express
• NestJS
• monorepos / pnpm workspaces / Turborepo / Nx signals

Python

• pip
• poetry
• uv
• FastAPI
• Django
• Flask
• Streamlit

Systems / compiled languages

• Go
• Rust
• C
• C++
• CMake-based C/C++ projects

---

Install

Recommended public install

pipx install autorunne

One-line installer for VS Code terminal users

curl -fsSL https://raw.githubusercontent.com/keguihua/autorunne/main/scripts/install.sh | bash

Install a pinned public release wheel with pipx

curl -fsSL https://raw.githubusercontent.com/keguihua/autorunne/main/scripts/install.sh \
  | AUTORUNNE_INSTALL_SOURCE=release-wheel AUTORUNNE_VERSION=v0.6.1 bash

This installs Autorunne with pipx, so you can open any repo in VS Code and immediately run:

autorunne open --with-vscode

Then just open the repo. Autorunne will auto-bootstrap or resume on open, and .autorunne/START_HERE.md becomes the agent entry point for Claude Code, Codex, Gemini, Hermes, Cursor, or GitHub Copilot.

Practical workflow: install Autorunne once globally; then for each repo run autorunne open --with-vscode once. After that you can open VS Code and launch Codex or Claude Code directly from that repo terminal. You do not need to keep a separate Autorunne window open unless you explicitly want autorunne daemon running.

Option A — local development install

git clone https://github.com/keguihua/autorunne.git
cd autorunne
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]

Option B — install from release asset

pip install autorunne-0.6.1-py3-none-any.whl

Fallback install modes

• AUTORUNNE_INSTALL_SOURCE=git → install directly from the GitHub repo
• AUTORUNNE_INSTALL_SOURCE=release-wheel → install a pinned GitHub Release wheel

---

Build installable packages

python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
python -m build

Build artifacts:

• dist/*.whl
• dist/*.tar.gz

---

Quick start

New repo

git init
autorunne init

Existing repo or cloned GitHub repo

autorunne open

Existing repo + VS Code auto integration

autorunne open --with-vscode

Run this once for each new repo. After that, opening the same repo in VS Code automatically refreshes .autorunne/ memory and task state, so you can launch Codex / Claude Code and continue immediately.

Keep a repo warm locally

autorunne daemon --duration 300 --interval 2
autorunne daemon --duration 300 --interval 2 --max-syncs 1

Push a Hermes chat task straight into local workflow memory

autorunne hermes-task \
  --task "Continue billing integration" \
  --next "Write Stripe webhook contract test" \
  --context "User asked Hermes to keep moving without re-explaining the repo"

Then point your coding agent at .autorunne/START_HERE.md or just continue from the repo after Autorunne opens it.

Start a focused task

autorunne start --task "Implement billing webhook" --next "Write webhook contract tests"

Save a checkpoint during development

autorunne checkpoint --summary "Mapped webhook payloads" --next "Implement handler wiring"

Refresh after meaningful work

autorunne sync --note "Finished auth fix, next handle dashboard filters"

Close one slice cleanly

autorunne finish --summary "Implemented auth fix" --next "Review dashboard filters"

Watch local changes and auto-sync

autorunne watch --duration 60 --interval 1

Health check

autorunne doctor

Export formal version

autorunne export

Build release bundle

autorunne release --version 0.6.1

---

Core commands

autorunne init

Create the workflow layer.

autorunne init
autorunne init --with-vscode

autorunne adopt

Scan an existing repository and generate workflow docs manually.

autorunne adopt
autorunne adopt --with-vscode

autorunne open

Auto-bootstrap a half-finished repo if .autorunne/ is missing, or resume the existing workflow memory if it already exists.

autorunne open
autorunne open --with-vscode

autorunne sync

Refresh workflow state, keep your manual memory docs intact, and append a manual note.

autorunne daemon

Run an open-first loop that bootstraps or resumes once, then keeps auto-syncing local file changes.

autorunne daemon --duration 300 --interval 2
autorunne daemon --duration 300 --interval 2 --max-syncs 1

• --max-syncs 1 is useful when you want the daemon to stop after the first meaningful auto-sync.
• Daemon output now shows the last changed files it synced.

autorunne hermes-task

Capture a task from a Hermes chat entry and write it straight into .autorunne/.

autorunne hermes-task \
  --task "Continue billing integration" \
  --next "Write Stripe webhook contract test" \
  --context "User asked Hermes to keep moving without re-explaining the repo"

autorunne start

Open a new task slice and put it into TASKS.md.

autorunne start --task "Implement billing webhook" --next "Write webhook contract tests"

autorunne checkpoint

Save progress mid-task without closing the task.

autorunne checkpoint --summary "Mapped webhook payloads" --next "Implement handler wiring"

autorunne finish

Close a real task, append a completion summary, optionally capture a durable decision, and run validation before setting the next action.

autorunne finish --summary "Implemented auth fix" --task "Review dashboard filters" --next "Ship release notes" --decision "Dashboard filters now reuse shared auth state"

To force a specific validation command:

autorunne finish --summary "Kept tests green" --validate "pytest -q" --next "Ship changelog"

autorunne watch

Watch the repository for file changes and auto-run sync.

autorunne watch --duration 120 --interval 1

autorunne doctor

Validate:

• workflow files
• .git/info/exclude
• git hooks
• VS Code integration
• pre-commit setup
• package artifacts

autorunne export

Create a clean formal export without .autorunne/.

autorunne release

Create a release bundle under .dist-release/releases/vX.Y.Z/ with:

• clean repo export
• release notes
• MANIFEST.json
• optional package assets

autorunne hooks

Install git hooks.

autorunne hooks
autorunne hooks --with-pre-commit

autorunne vscode

Create VS Code integration manually.

autorunne completion

Print shell completion setup instructions.

autorunne completion bash
autorunne completion zsh
autorunne completion fish

---

Generated workflow structure

.autorunne/
├── PROJECT_CONTEXT.md
├── TASKS.md
├── DECISIONS.md
├── SESSION_LOG.md
├── RULES.md
├── NEXT_ACTION.md
├── COMMANDS.md
├── START_HERE.md
├── agents/
│   ├── common.md
│   ├── claude-code.md
│   ├── codex.md
│   ├── hermes.md
│   └── cursor.md
└── snapshots/
    └── latest.json

This is the shared workflow core. Editors and coding tools can come and go, but the project workflow stays stable.

---

VS Code integration

VS Code is treated as an entry point, not the system core.

If you run:

autorunne open --with-vscode

or

autorunne init --with-vscode

autorunne creates:

• .vscode/tasks.json
• .vscode/settings.json
• .vscode/extensions.json

The generated task uses runOn: folderOpen, so VS Code can auto-trigger autorunne open when the workspace opens.

---

Team-friendly usage

autorunne hooks --with-pre-commit

This gives you:

• post-checkout sync
• post-merge sync
• pre-commit validation via autorunne doctor
• local .pre-commit-config.yaml bootstrap

---

Clean release separation

By default, autorunne writes .autorunne/ into:

.git/info/exclude

This keeps local workflow state out of normal repo history.

So you get:

• rich local Autorunne during development
• safe adoption for cloned open-source repos
• clean formal release output

---

Validation status

Validated locally for:

• generic repo initialization
• Node / React / Vite / Next.js / pnpm workspace / Turborepo detection
• Python / FastAPI detection
• Go detection
• Rust detection
• C and C++ / CMake detection
• VS Code auto integration
• release bundle generation
• shell completion output
• pre-commit and hook installation
• watcher-based auto-sync flow

Automated validation:

• pytest
• GitHub Actions on Python 3.11 and 3.12
• release workflow uploads wheel + source tarball

---

Install/use path for other developers

New project

1. create a repo
2. run autorunne init
3. point the coding agent at .autorunne/
4. work from NEXT_ACTION.md
5. run autorunne sync or autorunne watch
6. run autorunne export or autorunne release

Existing repo / cloned open-source repo

1. clone the repo normally
2. run autorunne adopt
3. optionally run autorunne open --with-vscode
4. keep .autorunne/ local-only
5. export or release a clean formal version when needed

---

Roadmap after 0.6.1

• publish to PyPI
• public pipx install flow
• smarter file watcher / daemon mode
• deeper monorepo graph awareness
• more editor entrypoints beyond VS Code
• stronger release automation (autorunne release + tag + changelog)

---

License

MIT