Arka

Your terminal, upgraded. Route plain English to 70+ local skills — deterministic offline routing, voice, 24-provider LLM failover, and security gates on by default.

Documentation: arka-agent.mintlify.site · Repository: github.com/Sumit884-byte/arka

Why Arka?

• Deterministic routing: 120+ symbolic rules handle most requests with zero LLM tokens before any model is called.
• Extensible: Add third-party skills via skill.json plugins — no fork required.
• Secure by default: Prompt-injection checks, risky-action prompts, and hard blocks on destructive shell patterns.
• Local-first: Skills run on your machine; LLM calls failover across Gemini, Groq, Ollama, and 20+ other providers.

If Arka looks useful, star the upstream repo — it helps others discover the project and signals that it's worth a look:

gh repo star Sumit884-byte/arka

Or open github.com/Sumit884-byte/arka and click Star.

Privacy

Arka is designed so you stay in control of your data:

• Runs on your machine — Skills execute locally. There is no hosted Arka account and no shared demo instance; your terminal, files, and config stay on your system.

• Local-first routing — 120+ symbolic rules handle many requests with zero LLM tokens, so common tasks never leave your machine.

• You choose where prompts go — LLM calls use only the providers you configure (Gemini, Groq, Ollama, etc.). For sensitive work, force a local-only boundary:

  arka run-only-local-llm "summarize this repo"
  arka hybrid config local-only
  

  With local-only, hosted providers are not used as fallbacks.

• Secrets stay local — API keys and .env live under your user config directory (~/.config/arka/ on Linux, ~/Library/Application Support/arka/ on macOS). arka integration setup never prints secret values.

• Memory stays local by default — Long-term memory uses a local cache unless you add a Supermemory key (MEMORY=auto falls back to local). Set MEMORY=local to keep recall entirely on disk.

• Web content is sanitized — Search results and scraped pages are stripped of suspicious injection patterns before they reach the model (SECURITY_SANITIZE=1 by default).

• Risky actions need confirmation — Installs, deletes, downloads, and automation prompt [y/N] unless you explicitly auto-confirm (SECURITY_ACTIONS=1 by default).

• Telemetry is opt-in — OpenTelemetry export to SigNoz or other backends is off until you enable OTEL_TRACES_ENABLED and set an endpoint.

Details: Security model · Memory · Hybrid local/hosted routing

Supported platforms

Platform	Support
macOS	Full support — recommended for daily use
Linux	Full support
Windows	Python CLI and arka subcommands work; the full 70+ skill router needs fish shell (scoop install fish or winget install fishshell). Without fish, Arka runs in portable mode with Python fallbacks. Some fish-oriented skills target macOS/Linux.

Requirements: Python 3.11+. Optional: fish shell for natural-language routing and voice integration.

Config paths: ~/.config/arka/ (Linux), ~/Library/Application Support/arka/ (macOS), %APPDATA%\arka\ (Windows).

Installation

PyPI package name is arka-agent — published at pypi.org/project/arka-agent.

Recommended (standalone, no clone, no build):

uv installs arka-agent from PyPI — no separate uv registry or token:

uv tool install "arka-agent[chat]"
arka setup
arka doctor

Or with pipx:

pipx install "arka-agent[chat]"
arka setup
arka doctor

One-off without global install:

uvx --from "arka-agent[chat]" arka doctor

Or with pip in a venv:

python3 -m pip install "arka-agent[chat]"
arka setup
arka doctor

GitHub fallback (if you need the latest commit before the next PyPI release):

pipx install "arka-agent[chat] @ git+https://github.com/Sumit884-byte/arka.git"
arka setup
arka doctor

From a git clone (best for contributors or tracking main):

Upstream (canonical):

git clone https://github.com/Sumit884-byte/arka.git
cd arka
./scripts/refetch.sh --install
arka setup
arka doctor

Working from a fork (recommended if you do not have push access to upstream):

gh repo fork Sumit884-byte/arka --clone
cd arka
./scripts/refetch.sh --install
pip install -e ".[chat,dev]"
arka setup
arka doctor

Example active fork: sumitmishra884byte-cpu/arka (fork of upstream). Sync your fork before opening a PR:

gh repo sync --source Sumit884-byte/arka
git push origin main

Configure API keys (at least one cloud key or local Ollama):

cp .env.example ~/.config/arka/.env   # macOS/Linux; see Supported platforms for Windows path

Add a free-tier key from Google AI Studio or Groq Console, then run arka free tier setup for recommended .env settings.

Optional one-liners:

brew install fish                    # macOS — unlocks full skill router
arka mcp doctor && arka mcp install   # verify MCP server; print Cursor snippet

See the Quickstart guide and MCP integration for fish setup, Cursor merge steps, and optional extras ([voice], [pdf], [all]).

Try Arka without building from source

There is no hosted demo instance or shared test account. The fastest path to evaluate Arka:

1. Browse the live docs — arka-agent.mintlify.site (skills catalog, routing concepts, CLI reference).

2. Install in one command — use the pip/pipx git install above (no manual build step).

3. Use free-tier LLM keys — Gemini and Groq both offer free tiers; Ollama is local and costs nothing:

   arka free tier setup
   arka doctor
   

4. Run sample commands that exercise routing and LLM failover:

   arka ask "what is Rust?"
   arka "convert 100 USD to INR"
   arka council "should I learn Rust?"
   arka quiz python
   arka coding-tui .
   arka repo_health scan
   

   Inside the coding TUI, /test scripts runs verification scripts discovered under scripts/ (no hardcoded list — Arka inspects filenames, docstrings, argparse, and test_* functions). Use /test for pytest and repo_health scan to see why each script matched.

5. Try MCP in Cursor — after install, arka mcp doctor then arka mcp install; merge the printed snippet into Cursor Settings → MCP and restart Cursor.

Full walkthrough: Quickstart · Free credits guide

Quick Start

Get to a working answer in under a minute:

arka doctor                              # verify install + keys
arka ask "what is Rust?"                 # web + AI answer
arka "convert 100 USD to INR"            # natural language routing
arka council "should I learn Rust?"      # multi-persona deliberation

Voice (optional):

arka listen    # then say: "hey arka, what's the weather"

More guides — skills, stocks, PDF RAG, Google Workspace, goal agent, testing — live on the documentation site.

Built with Codex & GPT-5.6

Arka was built for the OpenAI Build Week Developer Tools track (July 2026):

• Codex — routing rule hardening, NL routing test coverage, coding TUI iteration (/plan auto-execute, /test, /test scripts), and demo pipeline tooling.
• GPT-5.6 — primary model in the arka ask failover chain and agent steps inside arka coding-tui (via OpenRouter).

Judges can reproduce the full path with pipx install "arka-agent[chat]", arka setup, and arka doctor. Demo video and CLI screenshots live under recordings/.

Contributing

We welcome contributions of all sizes! Please read our Contribution Guidelines to get started with the local development workflow.

Quick fork workflow with GitHub CLI:

gh repo view Sumit884-byte/arka          # upstream metadata
gh repo fork Sumit884-byte/arka --clone  # your fork + local clone
cd arka
pip install -e ".[chat,dev]"
pytest
# push to your fork, then open a PR back to Sumit884-byte/arka
gh pr create --repo Sumit884-byte/arka

Look for the good first issue label on GitHub Issues to find a welcoming entry point.

License

Distributed under the GNU General Public License v2.0. See LICENSE for more information.