asicode

Autonomous Software Improvement — local safe patch runner and code editing tool: an AI-powered assistant for reading, analyzing, and modifying codebases with deterministic AST-level operations, transparent shell execution, and multi-language support.

Features

• Context economy: recent turns stay verbatim while older turns are compressed in the background, and superseded tool outputs are dropped from the window — long sessions stay focused and cheap instead of accumulating until a context cliff
• Autonomous long-run loop (/auto): after each turn the model drafts the natural next step as ghost text; auto mode countdown-runs it, chaining turns without a human prompt — a required-follow-up-only contract, a consecutive-step cap, and announced stop points keep the loop from wandering, and typing or Esc hands control back instantly
• Parallel sub-agents, mixed models: orchestration (--orchestrate) dispatches sub-tasks to worker processes — each opens its own terminal window on macOS — and every worker slot can run a different provider/model (/model dev_1 …)
• Multi-terminal, one repo: run several asi sessions on the same repository at once — cross-process file locks, per-turn ownership markers, and stale-worker reaping keep agents from duplicating or clobbering each other's work
• Claude Code collaboration: pair with the Claude Agent SDK for division of labor — Claude analyzes the codebase through asicode's MCP tools (read-only in analysis mode), asicode executes the edits, Claude optionally reviews the result (pip install 'asicode[collaborate]')
• Multi-language code editing: Python, TypeScript, JavaScript, Go, Java, Kotlin, Rust, and more via tree-sitter AST parsing
• AST-precise modifications: Edit symbols by name, insert/delete lines by anchor, apply typed AST operations (Python)
• Vector search & RAG: Semantic code search with FAISS + sentence-transformers embedding
• Structural analysis: Dead code detection, duplicate finding, unused import scanning, contradictory logic detection
• Interactive CLI: Rich terminal interface with prompt-toolkit, command history, completion, and multi-line editing
• Headless & automation modes: single-shot runs (asi -p), JSON/NDJSON output
• Self-searchable history: sessions persist to disk and survive /clear and CLI restarts — the model can search its own past conversations (search_design_history, cross-session) to recall decisions and file paths instead of re-discovering them
• Design chat: Persistent conversation session with insight management
• Shell shim layer: macOS/Linux compatibility layer for BSD-style command-line tools

Quick Start

# Recommended for CLI use: pipx installs into an isolated env and puts
# `asi` on your PATH, no venv activation needed
pipx install 'asicode @ git+https://github.com/socialherb/asicode.git'

# Or plain pip (inside a venv of your choice):
pip install git+https://github.com/socialherb/asicode.git

# Or with all features:
pip install 'asicode[all] @ git+https://github.com/socialherb/asicode.git'

# Start the interactive CLI
asi

Web UI

asicode also ships a local web UI — dashboard, agent panel and conversational design chat — served by FastAPI/uvicorn (bundled with the install):

uvicorn webapp.main:app --host 127.0.0.1 --port 8000
# then open http://127.0.0.1:8000/

By default only 127.0.0.1, localhost and ::1 Host headers are accepted — this is the DNS-rebinding defense, and it means a LAN/reverse-proxy deployment gets 403s until the hostnames your browser will actually use are allowlisted. Extend the list via ASICODE_ALLOWED_HOSTS (comma- or space-separated):

ASICODE_ALLOWED_HOSTS=192.168.0.10,myhost.local uvicorn webapp.main:app --host 0.0.0.0 --port 8000

Disallowed hosts are logged server-side with a pointer to ASICODE_ALLOWED_HOSTS, so the 403 is self-explanatory.

The agent panel runs autonomous agent tasks on a shared worker pool. The pool size is 10 by default; tune it via ASICODE_AGENT_MAX_WORKERS (values below 1 or non-numeric values fall back to the default):

ASICODE_AGENT_MAX_WORKERS=4 uvicorn webapp.main:app --port 8000

When all workers are busy, a queued run shows a "워커 대기 중" chip — including how many busy workers are parked on an approval/ask_user gate (blocked_on_gate), i.e. runs whose cards you can answer to free a slot immediately.

Installation Options

# Core (includes tree-sitter AST parsing — one package covers 300+ languages)
pip install asicode

# With RAG (vector search for code)
pip install 'asicode[rag]'

# With browser automation
pip install 'asicode[browser]'

# Development tools
pip install 'asicode[dev,lint]'

# Everything
pip install 'asicode[all]'

Architecture

asicode/
├── asi.py              # Interactive CLI (REPL)
├── external_llm/           # Core engine
│   ├── agent/              # Agent loop, tool handlers, verification
│   ├── languages/          # Multi-language providers (Python, TS, Go, etc.)
│   ├── editor/             # Code editing (AST, anchor, text, patch)
│   └── repl/               # Design chat session management
├── scripts/                # Lint/reachability guards (CI)
└── tests/                  # Test suite (unit + integration)

Key Concepts

Agent Tool Loop

Every request runs through a single LLM tool-use loop: the model reads, searches, and edits the repository through typed tools, and each write is followed by verification. Headless mode (asi -p) and orchestration mode (--orchestrate, which decomposes a request and dispatches it to parallel sub-agent workers) drive the same loop.

Auto-Continue: Long-Running Agent Loops (/auto)

After every turn asicode already suggests the natural next task as dim ghost text on the prompt (accept with →). /auto turns that suggestion into an unattended loop: the next step is auto-submitted after a short countdown, so a single instruction ("find and fix a bug, then keep going") can chain many turns of work — each one starting with a fresh tool loop, so long runs don't degrade the context window.

Autonomy is bounded by design, because an unattended loop must know when to stop:

• Opt-in only — /auto [N|on|off] is the sole trigger; intent is never inferred from prompt text. The prompt status line shows auto n/N while armed.
• Required-follow-up contract — the next step fires only when the previous turn left mandatory work (unverified changes, unfinished steps); "nice to have" ideas end the loop instead of extending it (NONE is the default).
• Announced stop points — natural completion, the consecutive-step cap (default 5), or an error turn all stop the loop with a visible notice rather than going silent.
• Instant takeover — typing cancels the pending step and resets the chain; Esc skips one step but keeps the mode; Enter on the empty prompt runs the step immediately. Auto-driven turns are tagged in the session record, so you can audit afterwards exactly how far the loop went on its own.

Context Economy

Most agent CLIs let every turn and tool result pile up until the context window forces a lossy compaction. asicode manages the window continuously:

• The most recent turns are always kept verbatim; older turns are summarized by a background pass that never blocks the conversation.
• Tool outputs feed the turn that requested them; once superseded, stale results are dropped from the window (originals persist on disk).
• Durable facts are promoted to a session insight store, so they survive compression instead of living in the transcript.
• Compressed and /clear-ed turns aren't gone — they're archived to disk, and the model can search back through them (and past sessions) with search_design_history whenever it needs a decision or file path that fell out of the active window.

The result: the model sees a focused window instead of a scrolling log — better attention on the task at hand, and materially fewer tokens per turn.

Parallel & Concurrent by Design

--orchestrate decomposes a request into sub-tasks and runs them in parallel worker processes over a file-based IPC protocol with heartbeats (a hung worker is distinguishable from a busy one). Worker slots are independently configurable, so a cheap fast model can handle mechanical edits while a stronger model plans.

Concurrency is also safe across your own terminals: session state is guarded by cross-process locks, each in-flight turn carries an owner marker so other sessions see "being handled elsewhere" instead of re-doing the work, and turns from crashed processes are detected and reaped.

Division of Labor with Claude Code

asi collaborate --task "…" runs a four-phase pipeline with the Claude Agent SDK, pairing each agent with what it does best:

1. Preprocess — asicode's cheap engine generates a codebase digest (structure, relevant files) so the expensive model never burns tokens on raw discovery.
2. Analyze — the Claude agent receives the digest and explores through asicode's in-process MCP tools; its own file tools are disabled and, in analysis mode, destructive tools are excluded — a read-only investigation by construction.
3. Execute — asicode applies the planned edits through its verified editing pipeline.
4. Review — optionally, the Claude agent reviews the execution and returns a verdict.

Requires the optional extra: pip install 'asicode[collaborate]'.

Deterministic Editing

All code modifications are validated through multiple layers:

• Syntax validation (AST parse gate)
• Structural analysis (dependency graph, import consistency)
• Verification loop (edit → verify → repair if needed)

Requirements

Python

• Python 3.10+
• macOS or Linux (BSD shim layer for macOS)

Bundled with the install

• ruff — the linter used for post-edit verification (F821 undefined-name checks). It is a core dependency, so pip install asicode installs it automatically. No separate step needed.
• tree-sitter — powers AST-based symbol/call/import detection for precise multi-language editing. The core install ships tree-sitter-language-pack (~2 MB) — a single package with full prebuilt-wheel platform coverage that covers every supported language out of the box (it also pulls in the tree-sitter core library automatically).

Recommended system tools

asicode degrades gracefully when these are missing, but installing them improves results:

Install git and ripgrep on macOS:

brew install git ripgrep

ripgrep can also be installed via the optional search extra (pip install asicode is unaffected if it fails — the grep fallback applies):

pip install 'asicode[search]'

Prebuilt wheels exist for macOS-arm64 and linux-x86_64; other platforms build from source.

Development

# Clone and install in editable mode
git clone <repo-url>
cd asicode
pip install -e '.[dev,lint,rag]'

# Run tests
pytest

# Coverage measurement — use the wrapper, NOT `coverage run -m pytest`:
# the default `-n auto` addopts makes xdist workers separate interpreters,
# so a plain coverage run records only the main process (~0%). scripts/cov.sh
# injects coverage into every process via COVERAGE_PROCESS_START (a1_coverage.pth,
# auto-created on first use) and merges the per-process data files with
# `coverage combine`.
./scripts/cov.sh [pytest args...]     # default: tests/unit -q
# CI (lint.yml unit job) runs the same wrapper and enforces the coverage
# ratchet in [tool.coverage.report] fail_under.

# Run linting
ruff check
ruff format --check

# Run type checking
pyright