{"id":43725577,"url":"https://github.com/flatmax/ai-coder-decoder","last_synced_at":"2026-05-10T02:06:35.084Z","repository":{"id":334319272,"uuid":"1140971391","full_name":"flatmax/AI-Coder-DeCoder","owner":"flatmax","description":"AC⚡DC the efficient AI Coder and DeCoder","archived":false,"fork":false,"pushed_at":"2026-02-01T11:24:23.000Z","size":903,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-02-01T18:15:26.918Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flatmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-24T02:35:24.000Z","updated_at":"2026-02-01T11:24:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/flatmax/AI-Coder-DeCoder","commit_stats":null,"previous_names":["flatmax/ai-coder-decoder"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/flatmax/AI-Coder-DeCoder","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatmax%2FAI-Coder-DeCoder","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatmax%2FAI-Coder-DeCoder/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatmax%2FAI-Coder-DeCoder/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatmax%2FAI-Coder-DeCoder/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flatmax","download_url":"https://codeload.github.com/flatmax/AI-Coder-DeCoder/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flatmax%2FAI-Coder-DeCoder/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29117916,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-05T05:31:32.482Z","status":"ssl_error","status_checked_at":"2026-02-05T05:31:29.075Z","response_time":65,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-02-05T09:01:33.082Z","updated_at":"2026-05-03T01:10:37.484Z","avatar_url":"https://github.com/flatmax.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# AC⚡DC — AI-assisted Code editing tool, De-Coder\nAC⚡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.\n**Reimplementation in progress.** This tree is a clean-room rebuild of AC⚡DC against a new specification suite. The user-facing feature set below describes the target — individual features land layer by layer and are tracked in [IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md).\n\n## Features\n\n- **Chat with any LLM** supported by [LiteLLM](https://docs.litellm.ai/) — Claude, GPT, DeepSeek, Bedrock, local models, and more.\n- **Structured code edits** with anchor-based matching, validation, and automatic git staging.\n- **Side-by-side diff viewer** — Monaco editor with hover, go-to-definition, references, and completions.\n- **SVG viewer \u0026 editor** — pan/zoom SVG files with inline editing: drag elements, reshape paths and curves, resize shapes, edit text in place, copy/paste/duplicate objects, and a full-width presentation mode (F11).\n- **File picker** with git status badges, diff stats, context menu, and keyboard navigation.\n- **Any LLM via [LiteLLM](https://docs.litellm.ai/)** — Claude, GPT, Gemini, Bedrock, Ollama, xAI, and 100+ more providers through one unified interface.\n- **Deterministic anchored edits** with emoji-delimited blocks, exact context matching, ambiguity detection, and automatic git staging. No fuzzy patching, no fenced-diff guessing.\n- **Stability-based four-tier prompt cache** (L0–L3 + active) with automatic promotion, demotion, ripple cascade, and provider cache-breakpoint alignment — pay to ingest once, subsequent requests hit cache.\n- **Tree-sitter symbol index** for Python, JavaScript, TypeScript, C, and C++ with cross-file reference graphs and LSP-style hover, go-to-definition, references, and completions inside the diff viewer.\n- **Document index** for markdown and SVG with keyword-enriched headings, containment-aware SVG outlines, and a cross-reference graph between documents.\n- **Cross-reference mode** — optional toggle that layers document outlines into code mode (and vice versa), so the LLM can trace how documentation references code without a full mode switch.\n- **Monaco-powered diff viewer** with LSP integration, markdown preview, TeX preview, markdown link provider (cross-file navigation), MATLAB syntax, and cross-file go-to-definition.\n- **Visual SVG editor** — click-to-select, drag-to-move, resize handles, path endpoint + control-point editing, inline text edit, marquee multi-selection, copy / paste / duplicate, undo, copy-as-PNG, and a full-width presentation mode.\n- **Code review mode** — pick a commit in a live git graph, soft-reset the branch, and work through the change with reverse diffs in context.\n- **Document conversion** — convert `.docx`, `.pdf`, `.pptx`, `.xlsx`, `.csv`, `.rtf`, `.odt`, `.odp` to markdown with extracted images and per-page SVG exports. PDFs use [PyMuPDF](https://pymupdf.readthedocs.io/) directly; presentations pipe through [LibreOffice](https://www.libreoffice.org/) → PDF → PyMuPDF, with python-pptx as fallback. Clean working tree required so output appears as reviewable diffs.\n- **URL chips** — paste a link; AC⚡DC detects it, fetches, summarises using the cheaper auxiliary model, and caches the content with per-message inclusion toggles. GitHub repos get a shallow clone + symbol-map summary.\n- **Images** — paste screenshots directly into chat; stored persistently under the per-repo working directory and re-attachable from history.\n- **Voice dictation** via the Web Speech API — toggle on the input, speak, and the transcript streams into the textarea.\n- **KaTeX math rendering** — display blocks via `$$...$$` and inline `$...$` inside chat messages.\n- **TeX preview** — live-rendered LaTeX preview for `.tex` files via make4ht + KaTeX with bidirectional scroll sync.\n- **File picker** with git status badges, diff stats, sort modes (name / mtime / size, each direction-toggleable), three-state exclusion checkboxes, context menus for every row type, inline rename / duplicate / new-file / new-directory, middle-click path insertion, `@`-filter from the chat input, active-file highlight, keyboard navigation, branch badge with detached-HEAD detection, and review-mode banner.\n- **2D file navigation grid** — opened files arrange spatially in a grid overlay; `Alt+Arrow` switches direction-wise without reaching for a tab bar.\n- **Full-text search** — two-panel layout with matching files (left) and line context with highlighting (right); regex, whole-word, case-sensitive modes; bidirectional scroll sync.\n- **Session history browser** — full-text search across JSONL history, per-session preview, load-into-session, and load-into-panel for ad-hoc comparison.\n- **History compaction** with LLM-powered topic boundary detection, a visible progress overlay, system-event messages in chat scrollback, and a live context-capacity bar showing budget pressure.\n- **Token HUD** — floating overlay with per-request and session-total token usage broken down by category.\n- **Copy diff to clipboard** — copy the working diff, or pick any local / remote branch from a fuzzy-searchable dropdown to copy the diff between working tree and that branch.\n- **Settings tab** — edit `llm.json` and `app.json` from the browser with hot-reload support.\n- **Collaboration mode** — multiple browsers connect to one backend over LAN. Host auto-admitted; subsequent clients require explicit approval. Non-localhost participants get a read-only view.\n- **Symmetric bidirectional JSON-RPC** over WebSocket via [jrpc-oo](https://github.com/flatmax/jrpc-oo) — terminal and browser are peers; either side can call the other.\n---\n## Philosophy\n- **Structural maps beat raw files.** The LLM receives compact, reference-annotated maps instead of full source text for most of the repo:\n  - *Code mode* — tree-sitter symbol map of classes, methods, imports, call sites, and cross-file references\n  - *Document mode* — keyword-enriched outline of markdown headings and SVG containment trees with cross-references\n  - *Cross-reference mode* — both indexes overlaid, so the LLM can trace \"this section mentions that function\" without switching modes\n- **Pay to ingest once.** Content unchanged across requests promotes through stability tiers and lands on provider cache breakpoints (e.g., Anthropic ephemeral caching). Large repos stop re-ingesting on every turn.\n- **Edits are mechanical.** Anchored blocks with exact-match context. Ambiguous or missing anchors surface as structured errors with retry prompts — never silent or fuzzy.\n- **Git is a first-class citizen.** Every applied edit is staged automatically. Commit messages are LLM-generated from the diff. The file picker shows git status and diff stats natively. Code review runs through soft-reset, not side branches.\n- **Local is the default.** Backend binds to loopback; non-localhost access requires explicit `--collab`. All persistent state lives in the repo's `.ac-dc4/` directory (history, images, doc cache). No cloud sync, no telemetry.\n- **Symmetric RPC.** Terminal and browser both implement the same jrpc-oo surface — streaming, progress events, session sync, file broadcasts all flow through one transport.\n---\n## Architecture\nSingle Python process exposes a WebSocket JSON-RPC server; the browser webapp connects and publishes its own callback interface. The process also serves the built webapp (or proxies a Vite dev server) on a separate port.\n```\n ┌────────────────────────────────────────────────────────────┐\n │                     Python backend                         │\n │                                                            │\n │  Repo ─┬─ SymbolIndex ──┐                                  │\n │        │                ├─▶ LLMService ◀─▶ ContextManager  │\n │        ├─ DocIndex ─────┘          │            │          │\n │        ├─ HistoryStore             │            │          │\n │        ├─ URLService               ▼            ▼          │\n │        ├─ DocConvert         StabilityTracker  FileContext │\n │        ├─ EditPipeline         (L0/L1/L2/L3)               │\n │        ├─ Settings                                         │\n │        └─ Collab                                           │\n │                 │                                          │\n │                 ▼  jrpc-oo over WebSocket                  │\n └────────────────────────────────────────────────────────────┘\n                  │\n ┌────────────────────────────────────────────────────────────┐\n │                      Browser webapp (Lit)                  │\n │                                                            │\n │  AppShell ──┬── FilesTab ──┬── FilePicker ─ ChatPanel      │\n │             │                                              │\n │             ├── ContextTab  (budget + cache sub-views)     │\n │             ├── DocConvertTab                              │\n │             ├── SettingsTab                                │\n │             │                                              │\n │             │  Viewer layer (background)                   │\n │             ├── DiffViewer  (Monaco + LSP + MD / TeX prev) │\n │             ├── SvgViewer + SvgEditor                      │\n │             │                                              │\n │             └── Overlays — TokenHUD, FileNavGrid,          │\n │                 CompactionProgress, DocIndexProgress       │\n └────────────────────────────────────────────────────────────┘\n```\nSee [specs4/0-overview/architecture.md](specs4/0-overview/architecture.md) and the SVG diagram at [specs4/architecture.svg](specs4/architecture.svg) for the full picture.\n---\n## Running\n### From source (uv)\n```\ngit clone https://github.com/flatmax/AI-Coder-DeCoder.git\ncd AI-Coder-DeCoder\n# Install Python dependencies (with dev extras)\nuv sync\n# Install webapp dependencies\ncd webapp \u0026\u0026 npm ci \u0026\u0026 cd ..\n```\nRun inside any git repository:\n```\ncd /path/to/your/project\n# Development mode — Vite HMR for the webapp\nuv run ac-dc --dev\n# Preview mode — pre-built webapp served locally\nuv run ac-dc --preview\n```\nStandalone binaries (Linux / macOS / Windows) are a deferred Layer 6 deliverable — see [specs4/6-deployment/build.md](specs4/6-deployment/build.md).\n### Optional extras\nDocument mode works out of the box with heading outlines, SVG containment trees, and cross-references. Richer features pull extras:\n```\n# Document conversion (markitdown, PyMuPDF, python-pptx, openpyxl) — small\nuv sync --extra docs-convert\n# Keyword enrichment (KeyBERT, sentence-transformers, torch) — large (~800 MB with CUDA wheels)\nuv sync --extra docs-enrich\n# Both\nuv sync --extra docs\n```\nSystem-level optional tools:\n| Tool | Purpose |\n|---|---|\n| [LibreOffice](https://www.libreoffice.org/) (`soffice` on PATH) | `.pptx` / `.odp` → PDF for the document-convert pipeline. Without it, `.pptx` falls back to python-pptx (basic SVG export). |\n| [make4ht](https://ctan.org/pkg/make4ht) (part of TeX Live) | Live TeX preview for `.tex` files. Without it, the preview pane shows installation instructions. |\n---\n## Provider Configuration\nOn first run, AC⚡DC creates a per-repo working directory at `.ac-dc4/` and a user-level config directory:\n| Platform | Config path |\n|---|---|\n| Linux | `~/.config/ac-dc/` (or `$XDG_CONFIG_HOME/ac-dc/`) |\n| macOS | `~/Library/Application Support/ac-dc/` |\n| Windows | `%APPDATA%\\ac-dc\\` |\nEdit `llm.json` in the user config directory to configure a provider.\n**AWS Bedrock:**\n```json\n{\n  \"env\": { \"AWS_REGION_NAME\": \"us-east-1\" },\n  \"model\": \"bedrock/us.anthropic.claude-sonnet-4-5-20250929-v1:0\",\n  \"smaller_model\": \"bedrock/us.anthropic.claude-haiku-4-5-20251001-v1:0\"\n}\n```\n**Anthropic direct:**\n```json\n{\n  \"env\": { \"ANTHROPIC_API_KEY\": \"sk-ant-...\" },\n  \"model\": \"anthropic/claude-sonnet-4-5-20250929\",\n  \"smaller_model\": \"anthropic/claude-haiku-4-5-20251001\"\n}\n```\n**OpenAI:**\n```json\n{\n  \"env\": { \"OPENAI_API_KEY\": \"sk-...\" },\n  \"model\": \"openai/gpt-5\",\n  \"smaller_model\": \"openai/gpt-5-mini\"\n}\n```\n**Local (Ollama):**\n```json\n{\n  \"env\": {},\n  \"model\": \"ollama/llama3\",\n  \"smaller_model\": \"ollama/llama3\"\n}\n```\nAny model supported by [LiteLLM](https://docs.litellm.ai/docs/providers) works. The `smaller_model` is used for commit-message generation, URL summarisation, and compaction topic-boundary detection. You can edit the config from the Settings tab inside the browser UI — `llm.json` and `app.json` hot-reload without a restart.\n---\n## Typical Workflow\n1. **Start** — `uv run ac-dc --dev` (or `--preview`) inside your git repo. Browser opens automatically.\n2. **Observe the startup overlay** — foundation, repository, indexing, and doc-index build in visible phases. The webapp becomes interactive as soon as the backend is reachable; indexing completes in the background.\n3. **Chat** — ask the LLM to understand, modify, or create code. The symbol map tells it which files are relevant without you naming them.\n4. **Add files to context** — click file mentions in the LLM response, or tick the file picker. Three states: selected (in context), unchecked (index-only), excluded (crossed out — omitted from both context and index).\n5. **Review edits** — applied edits appear in the diff viewer with per-line and per-character highlighting. Status badges show pending / applied / failed / ambiguous.\n6. **Commit** — use the header git controls. The smaller model drafts a conventional-commit message from the staged diff.\n7. **Iterate** — cache tiers evolve as you work; stability promotions reduce re-ingestion cost. The Token HUD shows per-request and session totals.\n### Code review sub-workflow\n1. Click the review button in the header.\n2. Select a commit in the git graph to set the review base.\n3. Click **Start Review** — the repo enters review mode (soft reset).\n4. Select files to include their reverse diffs in context.\n5. Chat with the LLM about the changes. Edits are blocked during review.\n6. Click **Exit Review** to restore the branch tip.\n---\n## Feature Tour\n### Chat + edit protocol\nMessages render as markdown with syntax highlighting (highlight.js) and KaTeX math. Responses stream chunk-by-chunk; edit blocks appear as inline diff cards with status badges.\nEdit blocks use a three-marker format — a filename line, an \"edit\" marker, the original text, a \"replace\" marker, the new text, and an \"end\" marker. The exact marker glyphs and contract are documented in [specs4/3-llm/edit-protocol.md](specs4/3-llm/edit-protocol.md) and [specs-reference/3-llm/edit-protocol.md](specs-reference/3-llm/edit-protocol.md) (this README avoids reproducing them inline because the chat-panel parser would interpret them as real edit blocks).\nFailures come with structured retry prompts:\n- **Ambiguous anchor** — matched multiple locations; chat panel auto-populates a retry prompt asking for more context\n- **Anchor not found** — whitespace or partial-match diagnostics\n- **Not in context** — file wasn't in file-context; auto-added and staged\n### Symbol index (code mode)\nTree-sitter builds a compact symbol map across the repo. Map legend covers abbreviations — `c` class, `m` method, `f` function, `i` import, `i→` local import, `←N` incoming refs, `→` outgoing calls, `?` optional param, `@1/` path alias. The LLM gets this map for files that aren't actively selected; selected files get full content.\nSupported languages: Python, JavaScript, TypeScript (plain + TSX), C, C++.\nLSP-style hover / go-to-definition / references / completions are exposed from the backend and wired into the Monaco diff editor. Cross-file go-to-definition opens the target in the diff viewer automatically.\n### Document index (document mode)\nMarkdown files produce a heading tree annotated with content-type markers (tables, code blocks, inline math) and section line counts. SVG files produce containment-aware outlines — nested shapes form a tree, labels come from `aria-label` / Inkscape labels / contained text, with spatial clustering as a fallback for shape-less diagrams.\nKeyword enrichment (optional — requires `docs-enrich` extras) runs KeyBERT with a TF-IDF fallback for short sections, boosting heading disambiguation for repetitive structures.\nCross-references resolve markdown `[text](path.md#heading)` links and image references, producing a reference graph that feeds cache-tier initialisation.\nRuntime toggle — code mode, document mode, or cross-reference mode (both indexes layered). No restart needed.\n### Cache tiering\nContent is tracked across categories (files, code symbols, doc outlines, URL context, history, system prompt) and flows through four stability tiers:\n- **Active** — just-added or recently changed; no promotion threshold\n- **L3 → L0** — increasing stability, aligned with provider cache breakpoints\nContent unchanged across N consecutive requests promotes; edited content demotes and ripples downward. Cache targets are model-aware (Opus / Haiku 4.5+ require higher minimums per Anthropic's docs). A manual rebuild rebalances tiers using the reference graph.\nSee [specs4/3-llm/cache-tiering.md](specs4/3-llm/cache-tiering.md).\n### History + compaction\nJSONL persistent history per-repo. Sessions are auto-saved and auto-restored on startup. The session browser supports full-text search across all sessions.\nCompaction fires when history exceeds a configurable token threshold (default 24 000). An auxiliary LLM call detects topic boundaries:\n- **Truncate case** — clear boundary found; drop everything before it\n- **Summarise case** — no clear boundary; summarise the older half into a short block, keep the verbatim window\nA capacity bar in the dialog footer shows live budget pressure (green / amber / red). Compaction progress appears as a floating overlay with elapsed-time counter. Successful compactions append a system-event message to the chat scrollback.\n### Diff viewer\nSingle-file, refetch-on-every-click, no caching. Monaco-based side-by-side diff editor with:\n- LSP integration (hover / definition / references / completions)\n- Markdown preview with bidirectional scroll sync\n- TeX preview (make4ht + KaTeX) with bidirectional scroll sync\n- Markdown link provider — Ctrl+click internal links to navigate\n- MATLAB syntax highlighting\n- Cross-file go-to-definition — navigates to the target in the same viewer\n- Load-panel — push any file content or commit diff into either side for ad-hoc comparison\n### SVG viewer \u0026 editor\nSVG files open in a dedicated viewer. Pan via middle-click-drag, zoom via scroll wheel (cursor-centred), side-by-side layout with synchronised viewports across both panes.\nThe editor on the right pane supports:\n- **Select** — click any element; bounding box or control-point handles appear\n- **Drag** — move any selected element (rects, circles, text, groups, paths, lines)\n- **Reshape paths** — draggable endpoint handles (blue circles) and control-point handles (orange diamonds) with guide lines\n- **Resize** — corner / edge handles on rects, circles, ellipses\n- **Line endpoints** — vertex handles on lines, polylines, polygons\n- **Inline text edit** — double-click a `\u003ctext\u003e` element; Enter commits, Escape cancels\n- **Multi-selection** — shift-click or marquee-drag\n- **Copy / paste / duplicate** — Ctrl+C / Ctrl+V / Ctrl+D\n- **Delete** — Delete or Backspace\n- **Undo** — per-editor undo stack\n- **Copy as PNG** — rasterise at native resolution into the clipboard\n- **Presentation mode** — full-width single pane via F11\n### TeX preview\nLive preview for `.tex` files via make4ht + KaTeX. Compiles on save (or debounced during typing), strips alt-text artefacts, renders math through KaTeX, injects source-line anchors for bidirectional scroll sync. Images and relative paths resolve through the repo. Graceful degradation when make4ht is missing — the pane shows installation instructions.\n### File picker\nFull keyboard navigation with a deep feature set:\n- **Git status badges** per file, **diff stats** (`+adds / -dels`), **line-count colouring**\n- **Branch badge** on the root node with detached-HEAD detection and SHA tooltip\n- **Sort modes** — name, mtime, size; each direction-toggleable with localStorage persistence\n- **Three-state exclusion** — selected / default / excluded via shift+click or context menu\n- **Active-file highlight** — picker row tracks the viewer's active file\n- **Context menus** — file row: stage / unstage / discard / rename / duplicate / load-left / load-right / include / exclude / delete. Directory row: stage-all / unstage-all / rename / new-file / new-directory / exclude-all / include-all\n- **Inline input** — rename / duplicate / new-file / new-directory all use in-place textboxes\n- **Middle-click** — inserts the file's path at the chat-input cursor\n- **`@`-filter bridge** — typing `@foo` in the chat input filters the picker in real time\n- **Auto-selection** — changed files auto-ticked on first load (union, never overwrite)\n- **Branch switcher** — dropdown with local + remote branches; aborts if the tree is dirty\n- **Review mode banner** — amber banner above the filter bar showing branch, commit count, file count, stats\n### File navigation grid\nOpened files arrange spatially on a 2D grid overlay. `Alt+Arrow` navigates directionally — left / right / up / down between adjacent open files. The HUD fades in while Alt is held. Travel counts track user preferences for replacement. Click-to-teleport, right-click to close a node, clear button to reset.\n### Search\nGlobal full-text search with two synchronised panels:\n- **Pruned tree** (left) — the file-picker tree filtered to matching files, with per-file match counts\n- **Match overlay** (right) — line-level matches with before / after context, highlighted\nModes: regex, whole-word, case-sensitive. Bidirectional scroll sync. Enter to open a match in the diff viewer.\n### Session history browser\nModal overlay listing sessions with token / message counts. Click a session to preview messages. Full-text search across all sessions surfaces individual hits. Actions per message: copy to clipboard, paste into chat input, load into diff viewer left / right panel.\n### Token HUD \u0026 Context tab\n**Token HUD** — floating overlay (appears post-stream, auto-hides after a configurable delay). Sections: cache tiers with per-tier content breakdown, current-request tokens, budget with category stacked bar, session totals.\n**Context tab** — two sub-views:\n- **Budget** — stacked bar of token usage by category (symbol map, files, history, URLs, prompt, active), with expandable per-file detail\n- **Cache** — tier breakdown with per-item stability progress, fuzzy search, sort by tier / alphabetical, rebuild-cache action, click-to-view per-item prompt blocks\n### Code review\nPick a commit from the interactive git graph; backend performs a soft-reset with detached-HEAD checkout. Review mode:\n- Swap system prompt to the review prompt (read-only instructions for the LLM)\n- Symbol map shows pre-change state; file diffs reverse (changes from new → old direction)\n- Selected files contribute reverse diffs to context\n- Edits are blocked; commits are blocked\n- Exit restores the branch tip and original branch\n### Document convert\nConvert documents to markdown from a dedicated tab. Supported formats: `.docx`, `.pdf`, `.pptx`, `.xlsx`, `.csv`, `.rtf`, `.odt`, `.odp`.\n- **Clean working tree required** — conversion results appear as diffs for review\n- **Provenance headers** embedded in output so re-conversions detect source changes\n- **Status badges** — new / current / stale / conflict / over-size / skipped\n- **PDF pipeline** — PyMuPDF extracts text plus per-page SVG with embedded images externalised to sibling files\n- **Presentation pipeline** — LibreOffice → PDF → PyMuPDF (primary); python-pptx fallback when LibreOffice is missing (basic SVG export)\n- **Excel pipeline** — openpyxl with cell-colour clustering, symbolised via emoji markers and a colour legend\n- **DOCX** — markitdown with image extraction from the underlying zip\n### URL content\nPaste any URL in chat; AC⚡DC detects it and shows a chip. Click the fetch button on the chip:\n- **Generic URLs** — trafilatura extracts main content, summarised by the smaller model\n- **GitHub repos** — shallow clone, extract README + symbol map, summary tuned for architecture\n- **GitHub files** — raw file fetch\n- **GitHub issues / PRs** — structured body + comments\nFetched content is cached under the OS temp directory with a TTL (default 24 h). Chips let you exclude individual URLs from the next message.\n### Images \u0026 voice\n- **Image paste** — drop screenshots into the chat input; stored persistently under `.ac-dc4/images/` keyed by SHA-256; auto-reconstructed on session reload; re-attachable from message history via lightbox\n- **Voice dictation** — toggle the microphone in the input area; Web Speech API streams the transcript live; configurable auto-commit mode\n### Collaboration\nCollaboration is disabled by default. Enable with `--collab`:\n```\nuv run ac-dc --collab\n```\nWhen enabled:\n- The WebSocket server binds to `0.0.0.0` (all network interfaces) instead of loopback\n- The first browser connection is auto-admitted as the **host**\n- Subsequent connections from other IPs are held pending until an admitted user clicks **Admit** in a toast\n- **Localhost clients** (including the host) have full control — chat, edit, commit, switch modes\n- **Non-localhost participants** get a read-only view — browse files, view diffs, watch streaming, read history. Edits, mode changes, and git operations are rejected with a `restricted` error\n- All broadcast events (streaming chunks, file changes, commit results, mode switches, session loads) reach every admitted client\nConnected-users indicator (`👥 N`) appears in the dialog header. Share the URL from the collab popover with LAN peers.\nSee [specs4/4-features/collaboration.md](specs4/4-features/collaboration.md) for the full contract.\n---\n## CLI Options\n| Flag | Default | Description |\n|---|---|---|\n| `--server-port` | `18080` | RPC WebSocket starting port (probes upward if taken) |\n| `--webapp-port` | `18999` | Webapp dev / preview starting port |\n| `--no-browser` | off | Don't auto-open the browser |\n| `--repo-path` | `.` | Git repository path |\n| `--dev` | off | Run a local Vite dev server (hot reload) |\n| `--preview` | off | Serve the pre-built webapp locally |\n| `--verbose` | off | Debug-level logging |\n| `--collab` | off | Enable collaboration mode (LAN-accessible, multi-browser) |\n---\n## Keyboard Shortcuts\n| Shortcut | Context | Action |\n|---|---|---|\n| `Enter` | Chat input | Send message |\n| `Shift+Enter` | Chat input | Newline |\n| `Up` | Chat input (empty) | Open input history |\n| `Escape` | Chat input | Clear `@`-filter → close snippets → clear input |\n| `@text` | Chat input | Filter file picker live |\n| `Ctrl+S` | Diff viewer / Settings / SVG editor | Save active file |\n| `Ctrl+F` | Diff viewer | Monaco find widget |\n| `Ctrl+Shift+F` | Global | Activate file search (captures current selection) |\n| `Alt+1` .. `Alt+4` | Global | Switch tab (Files / Context / Settings / Doc-Convert) |\n| `Alt+M` | Global | Toggle dialog minimize |\n| `Alt+Left/Right/Up/Down` | Global | File navigation grid |\n| `Scroll wheel` | SVG viewer | Zoom in / out (cursor-centred) |\n| `Middle-drag` | SVG viewer | Pan |\n| `F11` | SVG viewer | Toggle presentation mode |\n| `Escape` | SVG viewer (presentation) | Exit presentation |\n| `Click` | SVG editor | Select element |\n| `Drag handle` | SVG editor | Move endpoint / vertex / control point |\n| `Double-click` | SVG editor (text) | Edit text inline |\n| `Ctrl+C` / `Ctrl+V` / `Ctrl+D` | SVG editor | Copy / paste / duplicate |\n| `Delete` / `Backspace` | SVG editor | Delete selection |\n| `Escape` | SVG editor | Deselect / cancel text edit |\n| `Up` / `Down` / `Home` / `End` | File picker | Navigate tree |\n| `Left` / `Right` | File picker | Collapse / expand / traverse |\n| `Space` / `Enter` | File picker | Toggle selection / expand |\n| `Shift+Click` | File picker checkbox | Toggle exclusion (three-state) |\n| `Middle-click` | File picker (file row) | Insert path into chat input |\n---\n## Configuration\nConfig files live in the user config directory (platform-specific, see above). A subset can be overridden per-repo under `.ac-dc4/`.\n| File | Purpose | Format |\n|---|---|---|\n| `llm.json` | Provider, model, env vars, cache tuning | JSON |\n| `app.json` | URL cache, history compaction, doc convert, doc index settings | JSON |\n| `system.md` | Main LLM system prompt (code mode) | Markdown |\n| `system_doc.md` | Document mode system prompt | Markdown |\n| `review.md` | Code review system prompt | Markdown |\n| `system_reminder.md` | Edit-format reminder prepended to each user message | Markdown |\n| `system_extra.md` | Project-specific additions (user-owned, never overwritten) | Markdown |\n| `compaction.md` | Topic-boundary detection prompt | Markdown |\n| `commit.md` | Commit-message generation prompt | Markdown |\n| `snippets.json` | Quick-insert prompt buttons for code / review / doc modes | JSON |\nAll of these are editable from the Settings tab in the browser UI. `llm.json` and `app.json` hot-reload on save. Prompt files re-read on every request — edits take effect on the next LLM call.\n### LLM config fields\n| Field | Default | Description |\n|---|---|---|\n| `env` | `{}` | Environment variables injected on load (API keys, regions) |\n| `model` | (provider-specific) | Primary LLM model identifier |\n| `smaller_model` | (provider-specific) | Cheaper model for commit messages, URL summaries, compaction |\n| `max_output_tokens` | *(unset)* | User ceiling override for model output tokens |\n| `cache_min_tokens` | `1024` | User-configurable minimum cacheable token count |\n| `cache_buffer_multiplier` | `1.1` | Multiplier applied to the cache minimum for headroom |\n### App config sections\n| Section | Key fields |\n|---|---|\n| `url_cache` | `path`, `ttl_hours` |\n| `history_compaction` | `enabled`, `compaction_trigger_tokens`, `verbatim_window_tokens`, `summary_budget_tokens`, `min_verbatim_exchanges` |\n| `doc_convert` | `enabled`, `extensions`, `max_source_size_mb` |\n| `doc_index` | `keyword_model`, `keywords_enabled`, `keywords_top_n`, `keywords_ngram_range`, `keywords_min_section_chars`, `keywords_min_score`, `keywords_diversity`, `keywords_tfidf_fallback_chars`, `keywords_max_doc_freq` |\nFull field reference: [specs-reference/1-foundation/configuration.md](specs-reference/1-foundation/configuration.md).\n---\n## Per-Repo Working Directory\nA `.ac-dc4/` directory is created at the repo root on first run and added to `.gitignore`:\n| Entry | Contents |\n|---|---|\n| `history.jsonl` | Persistent conversation history (append-only) |\n| `images/` | Pasted-in chat images, keyed by SHA-256 |\n| `doc_cache/` | Keyword-enriched document outline cache (mtime-keyed sidecars) |\n| `tex_preview/` | Transient TeX compilation working directory (cleaned on startup) |\n| `snippets.json` | Optional per-repo override of quick-insert snippets |\nThe directory name is `.ac-dc4/` (not `.ac-dc/`) deliberately — this reimplementation coexists with the previous AC-DC on the same checkout without state collisions. See [IMPLEMENTATION_NOTES.md](IMPLEMENTATION_NOTES.md) decision D17.\n---\n## Development\n### Prerequisites\n- Python ≥ 3.10\n- Node.js ≥ 20 (for webapp development)\n- [uv](https://docs.astral.sh/uv/) recommended for Python dependency management\n### Setup\n```\ngit clone https://github.com/flatmax/AI-Coder-DeCoder.git\ncd AI-Coder-DeCoder\n# Python deps (dev group auto-included by uv sync)\nuv sync\n# Webapp deps\ncd webapp \u0026\u0026 npm ci \u0026\u0026 cd ..\n```\n### Run dev mode\n```\nuv run ac-dc --dev\n```\nStarts the Python backend plus Vite dev server with hot module replacement.\n### Run tests\n```\n# Python tests\nuv run pytest\n# Lint\nuv run ruff check src tests\n# Webapp tests (vitest)\ncd webapp \u0026\u0026 npm test\n```\n### Build webapp\n```\ncd webapp \u0026\u0026 npm run build\n```\n### Tech stack\n**Backend:**\n| Package | Purpose |\n|---|---|\n| [jrpc-oo](https://github.com/flatmax/jrpc-oo) | Bidirectional JSON-RPC 2.0 over WebSocket |\n| [LiteLLM](https://docs.litellm.ai/) | Universal LLM provider interface (100+ providers) |\n| [tiktoken](https://github.com/openai/tiktoken) | Token counting (cl100k_base for all models) |\n| [tree-sitter](https://tree-sitter.github.io/) | AST parsing for Python, JS/TS, C, C++ |\n| [trafilatura](https://trafilatura.readthedocs.io/) | Web page content extraction |\n| [boto3](https://boto3.amazonaws.com/v1/documentation/api/latest/) | AWS Bedrock support |\n| [markitdown](https://github.com/microsoft/markitdown) (extra) | Document-to-markdown |\n| [PyMuPDF](https://pymupdf.readthedocs.io/) (extra) | PDF text + SVG extraction |\n| [python-pptx](https://python-pptx.readthedocs.io/) (extra) | PowerPoint fallback |\n| [openpyxl](https://openpyxl.readthedocs.io/) (extra) | Excel with colour clustering |\n| [KeyBERT](https://maartengr.github.io/KeyBERT/) (extra) | Keyword enrichment |\n| [sentence-transformers](https://www.sbert.net/) (extra) | Embedding model for KeyBERT |\n**Frontend:**\n| Package | Purpose |\n|---|---|\n| [Lit](https://lit.dev/) | Web component framework |\n| [@flatmax/jrpc-oo](https://www.npmjs.com/package/@flatmax/jrpc-oo) | Browser JSON-RPC client |\n| [Monaco Editor](https://microsoft.github.io/monaco-editor/) | Diff editor with LSP |\n| [marked](https://marked.js.org/) | Markdown rendering |\n| [highlight.js](https://highlightjs.org/) | Syntax highlighting |\n| [KaTeX](https://katex.org/) | Math rendering |\n| [diff](https://github.com/kpdecker/jsdiff) | Edit-block diff computation |\n**Build:**\n| Tool | Purpose |\n|---|---|\n| [Vite](https://vitejs.dev/) | Webapp bundler / dev server |\n| [Vitest](https://vitest.dev/) | Webapp test runner |\n| [pytest](https://pytest.org/) | Backend test runner |\n| [ruff](https://docs.astral.sh/ruff/) | Backend linter |\n| [PyInstaller](https://pyinstaller.org/) | Standalone binaries (Layer 6, deferred) |\n---\n## Repository Layout\n```\nAI-Coder-DeCoder/\n├── src/ac_dc/                          # Python backend\n│   ├── __main__.py                     # python -m ac_dc entry\n│   ├── cli.py                          # argparse surface\n│   ├── main.py                         # server startup orchestration\n│   ├── config.py                       # configuration + upgrade logic\n│   ├── repo.py                         # git operations, file I/O, search\n│   ├── rpc.py                          # jrpc-oo server transport\n│   ├── collab.py                       # multi-browser admission + restrictions\n│   ├── settings.py                     # config read / write / reload RPC\n│   ├── file_context.py                 # active file context tracking\n│   ├── context_manager.py              # prompt assembly, token budget\n│   ├── history_store.py                # JSONL persistent history\n│   ├── history_compactor.py            # truncation + summarisation\n│   ├── stability_tracker.py            # four-tier cache cascade\n│   ├── token_counter.py                # tiktoken wrapper\n│   ├── edit_protocol.py                # edit block parser\n│   ├── edit_pipeline.py                # apply edits + git staging\n│   ├── llm_service.py                  # streaming, URL, review orchestration\n│   ├── doc_convert.py                  # document-to-markdown\n│   ├── logging_setup.py                # structured stderr logging\n│   ├── base_cache.py                   # mtime-based cache base\n│   ├── base_formatter.py               # compact-map formatter base\n│   ├── config/                         # bundled prompt + config defaults\n│   │   ├── llm.json\n│   │   ├── app.json\n│   │   ├── snippets.json\n│   │   ├── system.md\n│   │   ├── system_doc.md\n│   │   ├── review.md\n│   │   ├── commit.md\n│   │   ├── compaction.md\n│   │   └── system_reminder.md\n│   ├── doc_index/                      # markdown + SVG indexing\n│   │   ├── models.py\n│   │   ├── index.py\n│   │   ├── cache.py\n│   │   ├── formatter.py\n│   │   ├── reference_index.py\n│   │   ├── keyword_enricher.py\n│   │   └── extractors/\n│   │       ├── markdown.py\n│   │       ├── svg.py\n│   │       └── svg_geometry.py\n│   ├── symbol_index/                   # tree-sitter code indexing\n│   │   ├── models.py\n│   │   ├── parser.py\n│   │   ├── index.py\n│   │   ├── cache.py\n│   │   ├── compact_format.py\n│   │   ├── reference_index.py\n│   │   ├── import_resolver.py\n│   │   └── extractors/\n│   │       ├── python.py\n│   │       ├── javascript.py\n│   │       ├── typescript.py\n│   │       ├── c.py\n│   │       └── cpp.py\n│   └── url_service/                    # URL detection + fetch + summarise\n│       ├── detection.py\n│       ├── cache.py\n│       ├── fetchers.py\n│       ├── summarizer.py\n│       ├── models.py\n│       └── service.py\n├── webapp/                             # Lit-based browser webapp\n│   ├── package.json\n│   ├── vite.config.js\n│   └── src/\n│       ├── app-shell.js                # root component, WebSocket, routing\n│       ├── rpc.js                      # shared RPC proxy\n│       ├── rpc-mixin.js                # RPC access mixin for children\n│       ├── chat-panel.js               # chat messages + streaming + input\n│       ├── files-tab.js                # files + chat split panel\n│       ├── file-picker.js              # file tree with git status\n│       ├── context-tab.js              # budget + cache sub-views\n│       ├── settings-tab.js             # config editor\n│       ├── doc-convert-tab.js          # document conversion UI\n│       ├── diff-viewer.js              # Monaco diff editor\n│       ├── svg-viewer.js               # SVG pan/zoom viewer\n│       ├── svg-editor.js               # SVG element editor\n│       ├── markdown-preview.js         # markdown preview pane\n│       ├── tex-preview.js              # TeX preview pane\n│       ├── lsp-providers.js            # Monaco LSP glue\n│       ├── markdown-link-provider.js   # Ctrl+click markdown links\n│       ├── monaco-setup.js             # Monaco worker config\n│       ├── monaco-worker.js            # Monaco editor worker entry\n│       ├── edit-blocks.js              # edit block segmentation\n│       ├── edit-block-render.js        # inline diff card rendering\n│       ├── markdown.js                 # chat markdown rendering\n│       ├── message-search.js           # chat-local message search\n│       ├── history-browser.js          # session browser modal\n│       ├── input-history.js            # chat input history overlay\n│       ├── speech-to-text.js           # voice dictation\n│       ├── url-chips.js                # URL detection + fetch chips\n│       ├── url-helpers.js              # URL helpers\n│       ├── image-utils.js              # image paste + reattach\n│       ├── file-mentions.js            # file-mention click handling\n│       ├── file-nav.js                 # 2D navigation grid + HUD\n│       ├── viewer-routing.js           # extension → viewer dispatch\n│       ├── token-hud.js                # floating token overlay\n│       ├── compaction-progress.js      # compaction overlay\n│       ├── doc-index-progress.js       # doc-index build overlay\n│       ├── commit-graph.js             # git graph for code review\n│       └── main.js                     # Vite entry\n├── tests/                              # Python backend tests (pytest)\n├── scripts/\n│   └── sync_prompts.py                 # mirror prompts into specs-reference\n├── specs4/                             # Behavioural spec suite\n├── specs-reference/                    # Byte-level reference twin\n├── IMPLEMENTATION_NOTES.md             # Active reimplementation log\n├── pyproject.toml                      # uv / pip / hatch config\n└── LICENSE\n```\n---\n## License\nMIT — see [LICENSE](LICENSE).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatmax%2Fai-coder-decoder","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflatmax%2Fai-coder-decoder","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflatmax%2Fai-coder-decoder/lists"}