arka-agent 0.1.1

Cross-platform AI agent — chat, web answers, password vault, and skill routing

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

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.

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):

pipx install "arka-agent[chat]"
arka setup
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):

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

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.

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.