Arka

Arka upgrades your terminal: plain English in, 70+ local skills out. Offline routing first with 24 provider llm fallback orchestration, AI when you need it.

Comment

Arka — Hackathon / Project Submission

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

Area What we did
Coding TUI Session-based REPL with plan/run/test/ci/review commands, wired to the goal agent and readonly test runner
Script discovery New script_discovery.py — AST + regex heuristics to classify scripts as test/verify/check/ops without maintaining a manifest
MCP Exposed 30+ native tools via arka mcp serve; added self-tools discovery and NL routes for heartbeat/jsonkit
Remote UI Extended remote_server.py with a React frontend, Dockerfile, and railway.toml for one-click deploy
Docs Mintlify MDX with five tabs; icons on every sidebar entry
CI GitHub Actions for lint (ruff), tests (pytest), and PyPI publish on tagged releases

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 that we're proud of

  1. Shipped arka-agent 0.1.0 on PyPI — anyone can pipx install "arka-agent[chat]" and run arka setup without cloning the repo
  2. Coding TUI end-to-end loop — /plan → approve → auto-execute → /test with honest pytest output and optional auto-fix
  3. script_discovery.py — no hardcoded script manifest; heuristics find test/verify/smoke scripts in any repo
  4. Mintlify docs site — five tabs, icons everywhere, platform-specific install guides
  5. MCP in Cursor — documented config, self-tools discovery, NL routes in sync with terminal routing
  6. Remote coding UI on Railway — shareable demo without local setup
  7. 40+ commits in six days — routing, TUI, docs, MCP, 3D, slides, observability, CI — with Codex as a genuine force multiplier
  8. 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 for Arka

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

Built With

Share this project:

Updates