Arka

GitHub · PyPI: arka-agent · Docs

Inspiration

We wanted a local-first AI agent that actually does things in the terminal — not another chat window that hallucinates shell commands. Most assistants treat the repo as an afterthought: they guess test commands, miss project-specific scripts, and burn tokens on routing that should be deterministic. Arka started from a simple idea: route plain English to real, local skills with symbolic rules first and LLMs only when needed. Over the week of July 14–20, 2026, that grew into something we could ship: a PyPI package (arka-agent 0.1.0), a Mintlify docs site with real install paths, an interactive coding TUI for plan → execute → test loops, MCP tools for Cursor, and a hosted remote UI on Railway. We built Arka the way we wanted to use it — pair-programming with Codex in Cursor, letting the agent fix CI, write docs, discover scripts, and iterate on routing while we focused on architecture and product decisions.

What it does

Arka is your terminal, upgraded. It routes natural language to 70+ local skills using 120+ symbolic rules before any LLM is called. Core routing & dev workflows Deterministic NL routing for dev tasks: route audit, CI checks, code review, natural-language PR creation Symbolic URL repair and exact-url routing Screenshot-to-design project routing Language-agnostic lint project command Recurring self-improve scheduling Coding TUI — the centerpiece /plan — LLM-generated plans in plan-only mode, with local fallback /run — execute goals with resilient git handling and honest pytest reporting /test — strict read-only test mode vs. flexible /run tests with optional --fix /ci and /review shortcuts, enriched /status, auto-execute on plan approval Greenfield project support outside the Arka repo Agentic script discovery — script_discovery.py finds verification scripts under scripts/ via heuristics (stem patterns, docstrings, argparse), not hardcoded names; wired into repo_health and the coding TUI MCP & IDE integration arka mcp serve documented and configured for Cursor arka mcp self-tools — lists native MCP tools for self-discovery Heartbeat, jsonkit, and other MCP-exposed tools wired into NL routing Remote UI & hosting React-based remote coding demo with Dockerfile and Railway deploy config Profile tests for coding server behavior Creative & media skills 3D generation with free backends (Hugging Face, Meshy, procedural fallback) Slide composition with pitch/executive themes Deterministic 3D space scaffold with auto-install of trusted dependencies Docs, PyPI, and distribution Published arka-agent 0.1.0 on PyPI — pipx install "arka-agent[chat]" and go Mintlify docs at arka-agent.mintlify.site: five top-level tabs, sidebar icons on every page, install guides for macOS/Linux/Windows New guides: "How to code with Arka," hosted mode, MCP, loop engineering, and more

How we built it

We worked in a tight loop: Codex in Cursor + Arka itself, shipping ~40 commits in six days. Architecture Python 3.11+ monorepo with optional extras (chat, observability, 3d, video, etc.) in pyproject.toml fish shell as the NL router front-end; Python CLI (arka) as the skill dispatcher Symbolic routing layer (src/arka/routing/symbolic.py) handles most intents with zero tokens; LLM failover across 24 providers when needed Skill plugins via skill.json — no fork required to extend Key implementation decisions How Codex helped Codex was our pair-programming partner throughout: Routing fixes — caught coding-tui being misrouted to web_answer instead of the TUI skill CI triage — aligned MCP tests when Spotify tool was disabled; cleared ruff errors Test reliability — made /run tests call pytest honestly; handled skipped commands and bad JSON from the goal agent Script discovery — helped design the heuristic classifier and write tests (test_script_discovery.py) Docs — drafted Mintlify guides, tightened prose, added install paths and platform tables to README PyPI readiness — updated README with pipx install, GitHub fallback, and contributor clone paths We also dogfooded Arka: the self-improve loop re-indexed the repo, and we used the coding TUI's /plan → approve → auto-execute flow for feature work.

Challenges we ran into

Routing is harder than it looks Early in the week, typing "coding tui" in fish landed on web_answer instead of launching the TUI. We added explicit routes, tests for NL parsing, and a route-audit dev tool to catch mismatches. /run tests lied (briefly) The goal agent would report success without actually running pytest. We split concerns: /test always runs repo-detected tests directly; /run tests goes through the readonly goal agent unless --fix is passed. Codex helped trace the dishonest reporting path and write the fix. CI kept breaking on small changes Disabling the Spotify MCP tool broke tests that still expected it. Ruff flagged unused imports in CI-only paths. Each fix was small but blocked merges — Codex was useful for running the exact failing test, patching the assertion, and clearing lint in one pass. Greenfield vs. in-repo assumptions The coding TUI assumed it was always running inside the Arka repo. Greenfield projects outside Arka's scope crashed or skipped useful commands. We added scope detection and safer defaults. Docs sprawl Mintlify had orphaned pages and no consistent nav. Restructuring into five tabs and adding icons to every page took a dedicated push — tedious but necessary for a public launch. Remote UI + Railway Shipping a hosted demo meant Dockerfile, env examples (.env.railway.example), profile-specific server behavior, and profile tests. Getting the coding profile to behave correctly over HTTP was non-trivial.

Accomplishments we're proud of

Shipped arka-agent 0.1.0 on PyPI — anyone can pipx install "arka-agent[chat]" and run arka setup without cloning the repo Coding TUI end-to-end loop — /plan → approve → auto-execute → /test with honest pytest output and optional auto-fix script_discovery.py — no hardcoded script manifest; heuristics find test/verify/smoke scripts in any repo Mintlify docs site — five tabs, icons everywhere, platform-specific install guides MCP in Cursor — documented config, self-tools discovery, NL routes in sync with terminal routing Remote coding UI on Railway — shareable demo without local setup 40+ commits in six days — routing, TUI, docs, MCP, 3D, slides, observability, CI — with Codex as a genuine force multiplier Security by default — prompt-injection checks, risky-action prompts, and hard blocks on destructive shell patterns

What we learned

Deterministic routing first, LLM second. Every symbolic rule we added cut latency and made behavior predictable. The LLM is for planning and edge cases, not "what command should I run?" Split read-only from agent-assisted paths. Users need a trustworthy /test before they'll trust auto-fix. Dogfooding catches real bugs. Using the coding TUI on Arka itself surfaced greenfield assumptions and routing drift unit tests missed. AI pair programming works when scopes are clear. Codex excelled at CI fixes, test writing, docs prose, and routing bugs. We owned architecture (script discovery heuristics, MCP tool surface, TUI session model). Docs are part of the product. Restructuring Mintlify felt like overhead until someone installed from PyPI using only the docs site. Publish early. Getting 0.1.0 on PyPI forced us to nail install paths, platform tables, and arka doctor.

What's next

Near term Polish the remote UI — session persistence, file tree browsing, tighter integration with the local coding TUI Expand script discovery — support package.json scripts, Makefile targets, and monorepo layouts More MCP tools in NL routing — full self-tools surface reachable from fish without memorizing names Windows portable mode — document and test the Python-only fallback path more thoroughly Medium term Plugin marketplace — third-party skill.json plugins installable via arka skill install Team / hosted mode — build on Railway deploy and backend client work for shared agent sessions Observability defaults — one-command arka observability setup that instruments the agent itself Voice + multimodal — extend screenshot-to-design and 3D scaffolds to voice-driven coding sessions Long term Self-improve on autopilot — open PRs for routing gaps Arka finds in its own telemetry Cross-agent interoperability — Arka as the local execution layer for Cursor, Codex, Claude Code, and other IDE agents via MCP, with shared session memory