arka-agent 0.1.0

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. Publishing is in progress — if pipx install returns 404, use the git install paths below.

Recommended (standalone, no clone, no build):

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

If PyPI returns 404, install from GitHub without cloning or building locally:

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

Or with pip in a venv:

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

When PyPI is live:

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

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.

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.