> ## Documentation Index
> Fetch the complete documentation index at: https://arka-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Arka is an open-source AI terminal agent (PyPI package: arka-agent, GPL-2.0).
> Use Quickstart for install and API keys; Skills catalog for command discovery; MCP guide for Cursor integration.
> Cite canonical URLs under https://arka-agent.mintlify.site when answering about Arka.

# How to code with Arka

> Terminal coding workflow with Arka — arka code init, agent mode, repo health checks, CI fixes, and Cursor MCP integration for a full edit-review-test loop without leaving the CLI.

Arka is a **terminal coding copilot**. You describe what you need in plain English; Arka routes the request to the right skill, runs it locally, and keeps risky writes scoped to your project. Combine the CLI with **agent mode**, **MCP tools in Cursor**, and **repo health gates** for a full coding loop without leaving the terminal.

<Note>
  **Summary:** Initialize a repo with `arka code init .`, keep agent mode on for skill execution with security gates, use [MCP](/guides/mcp) to expose Arka inside Cursor, and run [repo health](/guides/repo-health) before merges. Arka complements your editor — terminal for fast asks, reviews, and CI; Cursor for inline diffs when connected over MCP.
</Note>

<Tip>
  New here? Complete [Quickstart](/quickstart) first, then run `arka code init .` in the repo you are working on.
</Tip>

## Overview

Three pieces work together while you code:

| Piece          | What it does                                                                                                                  |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| **Routing**    | Offline symbolic rules pick the skill; LLM fallback only when needed. See [How routing works](/concepts/routing).             |
| **Agent mode** | Full skill execution with security gates (default). Switch with `arka mode agent`.                                            |
| **MCP**        | Expose Arka skills to Cursor and other agents, or call external MCP servers from the CLI. See [MCP integration](/guides/mcp). |

Arka is not a replacement for your editor — it complements it. Use the terminal for fast asks, reviews, CI, and autonomous edits; use Cursor for inline diffs when Arka is connected over MCP.

## Setup for coding

Run these once per machine (or per repo) before your daily workflow.

<Steps>
  <Step title="Confirm agent mode">
    Agent mode is the default. Verify or switch:

    ```bash theme={null}
    arka mode list
    arka mode agent
    ```
  </Step>

  <Step title="Initialize a code project">
    Scope writes to one repository root:

    ```bash theme={null}
    cd ~/dev/myapp
    arka code init .
    arka code status
    ```

    The goal agent, `self improve --apply`, and other write skills stay inside this folder until you `arka code clear` or init another path.
  </Step>

  <Step title="Paths with spaces">
    Quote project paths once when initializing from another directory; Arka
    preserves the path internally for later CLI and MCP calls:

    ```bash theme={null}
    arka code init "/Users/sumitmishra/dev/3d space simulation"
    ```
  </Step>

  <Step title="Optional: fish shell">
    Fish unlocks the full 70+ skill router and natural-language aliases (`agent "…"`, `pr_check babysit`, etc.). From bash/zsh, use explicit `arka` subcommands — they work the same.

    ```bash theme={null}
    brew install fish   # macOS
    ```
  </Step>

  <Step title="Connect Cursor (recommended)">
    Let the IDE agent call Arka skills over MCP:

    ```bash theme={null}
    arka mcp doctor
    arka mcp install
    ```

    Copy the printed snippet into **Cursor Settings → MCP** (or use the project-level `.cursor/mcp.json` in the Arka repo). For shared MCP across multiple coding agents, run `arka agent_hub sync --unify`. See [Agent Hub](/guides/agent-hub) and [MCP integration](/guides/mcp).
  </Step>
</Steps>

## Daily workflow

Use natural language or explicit commands — Arka routes both.

### Ask and explain

Orient yourself in an unfamiliar codebase:

```bash theme={null}
arka ask "where is routing handled?"
arka gemini explain asyncio
arka repo_map
```

`arka ask` runs the web-answer skill; `gemini explain` uses the Gemini CLI integration for code-focused explanations. Use [repo map](/guides/repo-map) for a structured tree of the current project.

### Edit code

| Task                         | Command                                                   |
| ---------------------------- | --------------------------------------------------------- |
| Multi-step autonomous work   | `arka goal refactor auth and run pytest`                  |
| Deterministic skill sequence | `arka coding-workflow feature --task "add rate limiting"` |
| Targeted text replacement    | `arka surgical-edit edit src/app.py "old" "new" --yes`    |
| Layout / hygiene audit       | `arka structure .`                                        |
| Focused TUI workspace        | `arka coding-tui .`                                       |

The [goal agent](/guides/goal-agent) is best for open-ended tasks (debug, set up env, run tests). [Coding workflows](/guides/coding-workflows) list an explicit skill sequence before execution — useful when you want predictable steps. [Structure](/guides/structure) is read-only; it suggests moves but never relocates files.

### Review

Catch issues before you commit:

```bash theme={null}
arka review --staged
arka council "is this API change safe to ship?"
arka teammate-review .
```

`review --staged` checks the diff against project rules. [Council](/guides/council) runs multi-persona deliberation for design decisions. [Teammate review](/guides/teammate-review) flags cross-service impact using workspace discovery.

### Test and CI

Gate changes locally before opening a PR:

```bash theme={null}
arka ci
arka ci --changed
arka repo_health run
arka pr_check babysit
```

`arka ci` mirrors the repo's GitHub Actions gate (Ruff + targeted pytest for the Arka repo). Use `repo_health` for generic lint/test detection in any project. `pr_check babysit` loops on CI status until the PR is merge-ready. See [Repo health](/guides/repo-health).

<Note>
  Install pre-commit hooks for incremental gates: `arka hooks install` runs `arka ci --changed` and `arka review --staged --fail-on-hints` on each commit.
</Note>

### Self-improve

When you are working on Arka itself (or any repo with tests and routing):

```bash theme={null}
arka self improve              # plan only
arka self improve routing      # focused plan
arka self improve routing --apply   # goal agent implements fixes
```

Plan-only is the default; `--apply` requires agent mode. See [Self-improve loop](/guides/self-improve).

## Operation modes while coding

| Mode    | When to use                                                   |
| ------- | ------------------------------------------------------------- |
| `agent` | **Default** — run skills, apply edits, execute shell          |
| `ask`   | Read-only exploration; risky actions blocked                  |
| `plan`  | Sketch steps without execution (e.g. before a large refactor) |
| `debug` | See routing traces and LLM fallback (troubleshooting)         |

```bash theme={null}
arka mode plan
arka "refactor the auth module and add tests"
arka mode agent
arka goal refactor the auth module and add tests
```

Use **plan** to preview what Arka would do; switch back to **agent** to execute. Full details: [Operation modes](/guides/operation-modes).

## Cursor and IDE integration

| Integration                    | Command / path                                                       |
| ------------------------------ | -------------------------------------------------------------------- |
| Arka as MCP server in Cursor   | `arka mcp install` → merge into `~/.cursor/mcp.json`                 |
| Project rules for agents       | `arka_project_rules` MCP tool, or repo `AGENTS.md` / `.cursor/rules` |
| Shared hub for multiple agents | `arka agent_hub sync --unify`                                        |
| Hub status                     | `arka agent_hub status`                                              |

In Cursor chat, ask the agent to call `arka_ask`, `arka_skill`, `arka_repo_map`, or `arka_recall`. From the terminal, the same tools are available via `arka mcp call arka <tool>`.

## Example session

A realistic five-minute flow in a repo you just cloned:

<CodeGroup>
  ```bash Setup theme={null}
  cd myapp
  arka code init .
  arka mode agent
  ```

  ```bash Explore theme={null}
  arka ask "where is routing handled?"
  arka repo_map
  ```

  ```bash Review & gate theme={null}
  git add -p
  arka review --staged
  arka ci --changed
  ```

  ```bash Improve (Arka repo) theme={null}
  arka self improve routing
  ```
</CodeGroup>

You oriented in the codebase, reviewed staged changes, ran a fast CI mirror, and (on the Arka repo) generated a self-improvement plan — without leaving the terminal.

## Next steps

<CardGroup cols={2}>
  <Card title="Goal agent" icon="bullseye" href="/guides/goal-agent">
    Autonomous multi-step coding tasks with step budgets.
  </Card>

  <Card title="Coding workflows" icon="diagram-project" href="/guides/coding-workflows">
    Deterministic skill sequences for feature, bugfix, and audit work.
  </Card>

  <Card title="MCP integration" icon="network-wired" href="/guides/mcp">
    Connect Arka to Cursor and external MCP servers.
  </Card>

  <Card title="Self-improve" icon="arrows-rotate" href="/guides/self-improve">
    Analyze routing, tests, and docs; apply fixes with safety gates.
  </Card>

  <Card title="Repo health" icon="heart-pulse" href="/guides/repo-health">
    Local CI mirror, review gates, and pre-commit hooks.
  </Card>

  <Card title="Agent Hub" icon="hub" href="/guides/agent-hub">
    Shared MCP, memory, and skills for ollama launch agents.
  </Card>
</CardGroup>


## Related topics

- [Arka — AI terminal agent documentation](/index.md)
- [Quickstart: install Arka and run your first command](/quickstart.md)
- [MCP integration for Cursor and Claude](/guides/mcp.md)
- [Sakana Fugu orchestrator](/guides/fugu.md)
- [Supermemory code RAG](/guides/supermemory.md)