AC⚡DC is an AI pair-programming tool that runs as a terminal application with a browser-based UI. It helps developers navigate codebases, chat with LLMs, and apply structured file edits — all with intelligent prompt caching to minimize costs.
demo.general.webm
Slow version
demo.general.trimmed.mp4
- Chat with any LLM supported by LiteLLM — Claude, GPT, DeepSeek, Bedrock, local models, and more.
- Structured code edits with anchor-based matching, validation, and automatic git staging.
- Side-by-side diff viewer — Monaco editor with hover, go-to-definition, references, and completions.
- SVG viewer & editor — pan/zoom SVG files with inline editing: drag elements, reshape paths and curves, resize shapes, edit text in place, and copy/paste/duplicate objects.
- File picker with git status badges, diff stats, context menu, and keyboard navigation.
- Code review mode — select a commit, soft reset, and discuss changes with the LLM.
- URL detection and fetching — paste a link and AC⚡DC fetches, summarizes, and caches the content. Works with GitHub repos too.
- Image paste support — drop screenshots into chat with persistent storage across sessions.
- Voice dictation via Web Speech API.
- Configurable prompt snippets for common actions.
- Full-text search across the repo with regex, whole-word, and case-insensitive modes.
- Session history browser — search, revisit, and reload past conversations.
- Tree-sitter symbol index across Python, JavaScript/TypeScript, and C/C++ with cross-file references.
- Document mode — toggle to a documentation-focused context where markdown and SVG outlines replace code symbols. Keyword-enriched headings and cross-reference graphs help the LLM navigate doc-heavy repos. Install
pip install ac-dc[docs]for keyword extraction support (optional — document mode works without it). - Four-tier prompt cache (L0–L3 + active) with automatic promotion, demotion, and cascade rebalancing.
- History compaction with LLM-powered topic boundary detection to keep long sessions within context limits.
- Token HUD with per-request and session-total usage reporting.
- Symbol map, not full files — A compact, reference-annotated map of your codebase gives the LLM structural context without burning tokens on full file contents. In document mode, the map switches to keyword-enriched document outlines with cross-reference links.
- Stability-based caching — Content that stays unchanged across requests promotes to higher cache tiers, aligning with provider cache breakpoints (e.g., Anthropic's ephemeral caching). You pay to ingest once; subsequent requests hit cache.
- Deterministic edits — The LLM proposes changes using anchored edit blocks with exact context matching. No fuzzy patching, no guessing.
- Visual SVG editing — SVG files open in a dedicated viewer with pan/zoom and a structural editor. Select, drag, reshape, and duplicate elements directly — no external tools needed.
- Git-native — Every applied edit is staged automatically. Commit messages are LLM-generated. The file picker shows git status natively.
- Bidirectional RPC — Terminal and browser are symmetric peers over WebSocket (JSON-RPC 2.0). Either side can call the other.
- Start — Run
ac-dcin your git repo. Browser opens automatically. - Select files — Check files in the picker to add their full content to context.
- Chat — Ask the LLM to understand, modify, or create code.
- Review edits — Applied edits appear in the diff viewer with two-level highlighting. SVG files open in a dedicated viewer with pan/zoom and inline editing.
- Commit — Click 💾 to stage all, generate an LLM commit message, and commit.
- Iterate — File context and cache tiers evolve as you work.
demo.review.webm
Slow version
demo.review.trimmed.mp4
- Click the review button in the header bar.
- Select a commit in the git graph to set the review base.
- Click Start Review — the repo enters review mode (soft reset).
- Select files to include their reverse diffs in context.
- Chat with the LLM about the changes.
- Click Exit Review to restore the branch.
SVG files (.svg) open in a dedicated viewer instead of the Monaco diff editor. The viewer provides:
- Pan & zoom — scroll wheel to zoom (centered on cursor), middle-click drag to pan.
- Side-by-side view — original (left) and current (right) panels synchronized for zoom and pan.
- Edit mode — switch to the editor to modify SVG elements directly:
- Select — click any element to select it. A bounding box or control-point handles appear depending on the element type.
- Drag — move any selected element (rects, circles, text, groups, paths, lines, etc.).
- Reshape paths — for
<path>elements (lines, curves, arcs), draggable handles appear at every endpoint (blue circles) and control point (orange diamonds), with guide lines showing the curve structure. Drag any handle to reshape the path. - Resize shapes —
<rect>,<circle>, and<ellipse>elements show corner/edge handles for resizing. - Line endpoints —
<line>,<polyline>, and<polygon>elements show vertex handles for individual point dragging. - Edit text — double-click a
<text>element to edit its content inline. Enter commits, Escape cancels. - Copy/paste —
Ctrl+Ccopies,Ctrl+Vpastes with an offset,Ctrl+Dduplicates in place. - Delete —
DeleteorBackspaceremoves the selected element.
- Undo — revert to previous states.
- Save —
Ctrl+Sor the save button writes changes back to disk.
Download the latest standalone binary for your platform from the GitHub Releases page:
| Platform | Binary |
|---|---|
| Linux | ac-dc-linux |
| macOS (ARM) | ac-dc-macos |
| Windows | ac-dc-windows.exe |
Then run it inside any git repository:
cd /path/to/your/project
./ac-dc-linuxAC⚡DC opens your browser and connects via WebSocket. The terminal stays running as the backend.
Note: The standalone binary includes full document mode support (heading outlines, cross-references, cache tiering), but keyword-enriched headings require the Python
keybertpackage which is not bundled. If you want keyword extraction for better disambiguation of repetitive document structures, run from source and install withpip install ac-dc[docs].
On first run, AC⚡DC creates a .ac-dc/ directory in your repo. Edit .ac-dc/llm.json with your provider credentials:
AWS Bedrock:
{
"env": { "AWS_REGION": "us-east-1" },
"model": "bedrock/anthropic.claude-sonnet-4-20250514",
"smallerModel": "bedrock/anthropic.claude-haiku-4-5-20251001-v1:0"
}Anthropic direct:
{
"env": { "ANTHROPIC_API_KEY": "sk-ant-..." },
"model": "anthropic/claude-sonnet-4-20250514",
"smallerModel": "anthropic/claude-haiku-4-5-20251001-v1:0"
}OpenAI:
{
"env": { "OPENAI_API_KEY": "sk-..." },
"model": "openai/gpt-4o",
"smallerModel": "openai/gpt-4o-mini"
}Local (Ollama):
{
"env": {},
"model": "ollama/llama3",
"smallerModel": "ollama/llama3"
}Any model supported by LiteLLM works. You can also edit the configuration from the Settings tab inside the browser UI.
| Shortcut | Context | Action |
|---|---|---|
Enter |
Chat input | Send message |
Shift+Enter |
Chat input | New line |
↑ |
Chat input (empty) | Open input history |
Escape |
Chat input | Clear @-filter → close snippets → clear input |
@text |
Chat input | Filter file picker |
Ctrl+S |
Diff viewer / Settings | Save file |
Ctrl+Shift+F |
Global | Open search tab with selection |
Alt+1 |
Global | Files & Chat tab |
Alt+2 |
Global | Search tab |
Alt+3 |
Global | Context Budget tab |
Alt+4 |
Global | Cache Tiers tab |
Alt+5 |
Global | Settings tab |
Alt+M |
Global | Toggle minimize dialog |
↑/↓ |
Search results | Navigate matches |
Enter |
Search results | Open match in diff viewer |
Space/Enter |
File picker | Toggle file selection |
↑/↓ |
File picker | Navigate tree |
Scroll wheel |
SVG viewer | Zoom in/out (centered on cursor) |
Middle-drag |
SVG viewer | Pan the viewport |
Click |
SVG editor | Select element (shows handles) |
Drag |
SVG editor | Move selected element |
Drag handle |
SVG editor | Move endpoint, vertex, or control point |
Double-click |
SVG editor (text) | Edit text inline |
Enter |
SVG editor (text) | Commit text edit |
Ctrl+C |
SVG editor | Copy selected element |
Ctrl+V |
SVG editor | Paste with offset |
Ctrl+D |
SVG editor | Duplicate in place |
Delete |
SVG editor | Delete selected element |
Escape |
SVG editor | Deselect / cancel text edit |
| Flag | Default | Description |
|---|---|---|
--server-port |
18080 |
RPC WebSocket port |
--webapp-port |
18999 |
Webapp dev/preview port |
--no-browser |
false |
Don't auto-open browser |
--repo-path |
. |
Git repository path |
--dev |
false |
Run local Vite dev server |
--preview |
false |
Build and preview locally |
--verbose |
false |
Enable debug logging |
All configuration lives in src/ac_dc/config/ (bundled defaults) or {repo_root}/.ac-dc/ (per-repo overrides).
| File | Purpose | Format |
|---|---|---|
llm.json |
Provider, model, env vars, cache tuning | JSON |
app.json |
URL cache, history compaction settings | JSON |
system.md |
Main LLM system prompt | Markdown |
system_extra.md |
Additional project-specific instructions | Markdown |
system_doc.md |
Document mode system prompt | Markdown |
snippets.json |
Quick-insert prompt buttons | JSON |
doc-snippets.json |
Document mode snippet buttons | JSON |
compaction.md |
History compaction skill prompt | Markdown |
review.md |
Code review system prompt | Markdown |
review-snippets.json |
Review mode snippet buttons | JSON |
| Field | Default | Description |
|---|---|---|
env |
{} |
Environment variables (API keys, regions) |
model |
— | Primary LLM model identifier |
smallerModel |
— | Cheaper model for summaries and commit messages |
cache_min_tokens |
1024 |
Minimum tokens for cache tier targeting |
cache_buffer_multiplier |
1.5 |
Multiplier for cache target (1024 × 1.5 = 1536) |
| Field | Default | Description |
|---|---|---|
url_cache.path |
/tmp/ac-dc-url-cache |
URL content cache directory |
url_cache.ttl_hours |
24 |
Cache expiry in hours |
history_compaction.enabled |
true |
Enable automatic history compaction |
history_compaction.compaction_trigger_tokens |
24000 |
Token threshold to trigger compaction |
history_compaction.verbatim_window_tokens |
4000 |
Recent tokens kept verbatim |
history_compaction.summary_budget_tokens |
500 |
Max tokens for compaction summary |
history_compaction.min_verbatim_exchanges |
2 |
Minimum recent exchanges always kept |
All configs are editable from the Settings tab in the browser UI with hot-reload support.
If you prefer running from a clone instead of the standalone binary:
git clone https://github.com/flatmax/AI-Coder-DeCoder.git
cd AI-Coder-DeCoder
pip install -e .Then run inside any git repo:
cd /path/to/your/project
ac-dcThe webapp is served from GitHub Pages — no local build step needed.
- Python ≥ 3.10
- Node.js ≥ 18 (for webapp development)
git clone https://github.com/flatmax/AI-Coder-DeCoder.git
cd AI-Coder-DeCoder
# Install Python dependencies (with dev extras)
pip install -e ".[dev]"
# Optional: install document mode keyword extraction (KeyBERT + sentence-transformers)
pip install -e ".[docs]"
# Install webapp dependencies
npm installac-dc --devThis starts both the Python RPC server and a Vite dev server with hot module replacement.
pytestnpm run buildBackend (Python):
| Package | Purpose |
|---|---|
| jrpc-oo | Bidirectional JSON-RPC 2.0 over WebSocket |
| LiteLLM | Universal LLM provider interface (100+ providers) |
| tiktoken | Model-aware token counting |
| Tree-sitter | AST parsing for symbol extraction (Python, JS/TS, C/C++) |
| trafilatura | Web page content extraction |
| boto3 | AWS Bedrock support |
Frontend (JavaScript):
| Package | Purpose |
|---|---|
| Lit | Web component framework |
| @flatmax/jrpc-oo | Browser-side JSON-RPC client |
| Monaco Editor | Side-by-side diff editor |
| Marked | Markdown rendering |
| highlight.js | Syntax highlighting |
| diff | Myers diff algorithm for edit block display |
Build & Deploy:
| Tool | Purpose |
|---|---|
| Vite | Webapp bundler and dev server |
| PyInstaller | Standalone binary packaging |
| GitHub Actions | CI/CD for releases and GitHub Pages deployment |
.github/workflows/
deploy-pages.yml
release.yml
specs3/ # Specification documents
1-foundation/
2-code-analysis/
3-llm-engine/
4-features/
5-webapp/
6-deployment/
src/ac_dc/
__init__.py
config.py # Configuration loading and management
context.py # Context manager, file context, prompt assembly
edit_parser.py # Edit block parsing, validation, application
history_compactor.py # History truncation and summarization
history_store.py # JSONL persistent history
llm_service.py # LLM streaming, context orchestration, review mode
main.py # CLI entry point, server startup
repo.py # Git operations, file I/O, search
settings.py # Config read/write/reload RPC service
stability_tracker.py # Cache tier N-value tracking and cascade
token_counter.py # Model-aware token counting
topic_detector.py # LLM-based topic boundary detection
url_cache.py # Filesystem TTL cache for URLs
url_handler.py # URL detection, fetching, summarization
config/ # Default configuration files
app.json
compaction.md
doc-snippets.json # Document mode snippet buttons
llm.json
review-snippets.json
review.md
snippets.json
system.md
system_doc.md # Document mode system prompt
system_extra.md
system_reminder.md # Injected before each user message
doc_index/
__init__.py
cache.py # mtime-based document cache
formatter.py # Compact outline text output
index.py # Orchestrator, repo-wide indexing
keyword_enricher.py # Optional KeyBERT keyword extraction
reference_index.py # Cross-file doc/code reference graph
extractors/
__init__.py
base.py # Base extractor class
markdown_extractor.py
svg_extractor.py
symbol_index/
__init__.py
cache.py # mtime-based symbol cache
compact_format.py # LLM-optimized text output
index.py # Orchestrator, LSP queries
parser.py # Tree-sitter multi-language parser
reference_index.py # Cross-file reference tracking
import_resolver.py # Import-to-file resolution
extractors/
__init__.py
base.py # Base extractor class
python_extractor.py
javascript_extractor.py
c_extractor.py
tests/
test_config.py
test_context.py
test_edit_parser.py
test_history.py
test_llm_service.py
test_main.py
test_repo.py
test_stability_tracker.py
test_symbol_index.py
test_url_handler.py
webapp/
index.html
src/
app-shell.js # Root component, WebSocket, event routing
rpc-mixin.js # Shared RPC access for child components
shared-rpc.js # Singleton call proxy
styles/
theme.js # Design tokens and shared styles
utils/
edit-blocks.js # Edit block segmentation and diffing
markdown.js # Markdown rendering with syntax highlighting
components/
ac-cache-tab.js # Cache tier viewer
ac-context-tab.js # Context budget viewer
ac-dialog.js # Main dialog container with tabs
ac-files-tab.js # Files & chat split panel
ac-history-browser.js # Session browser modal
ac-search-tab.js # Full-text search
ac-settings-tab.js # Configuration editor
chat-panel.js # Chat messages, streaming, input
diff-viewer.js # Monaco diff editor
svg-viewer.js # SVG pan/zoom viewer with side-by-side
svg-editor.js # SVG element editor (drag, resize, path editing)
file-picker.js # File tree with git status
input-history.js # Input history overlay
review-selector.js # Git graph for code review
speech-to-text.js # Voice dictation
token-hud.js # Floating token usage overlay
url-chips.js # URL detection and fetch chips
MIT