# Aiur

Aiur (AI Unit Runtime) runs autonomous coding agents against work in a
project tracker. It gives each selected issue an isolated workspace, launches
Codex or Claude to implement the work, and keeps the run moving through review
and terminal states. A CLI and TUI show the active agents and provide live
chat; Aiur also has a web dashboard for observing a run.

Aiur is prototype software for trusted environments. It bypasses agent
permission prompts. Each worker gets a dedicated workspace and checkout, but
that separation is not by itself a security boundary; the configured backend
sandbox policy determines whether an agent can access host resources outside
its workspace. Aiur's intended workflow routes changes through the Executor's
review gates and merge policy rather than having agents self-merge.

## Operating model

Every Aiur run has an **Executor**: the operator of the run. That is either the
human, driving the CLI directly, or the human's coding agent, operating Aiur on
their behalf while they stay in conversation with it. Both modes are
first-class and supported by design.

- **Human-driven.** A person runs `aiur`, uses the CLI/TUI to answer agents and
  apply merge policy, and observes the run in the dashboard. The dashboard is
  read-only by default; configured writable mode adds its supported controls.
- **Agent-driven.** A coding agent (Claude Code, Codex) operates Aiur as the
  Executor — launching, monitoring, recovering stuck agents, coordinating PR
  review — while the human converses with that agent in parallel. The repository
  source repository bundles skills for this: `.claude/skills/aiur-intro` (what Aiur is, install,
  choosing a mode), `.claude/skills/aiur-run` (operate a run end to end as its
  Executor), and `.claude/skills/aiur-monitor` (status board and alert feed).
  The npm CLI package does not install those repo-local coding-agent skills.

Mixing is common: the agent runs the code-to-PR stretch while operations needing
production credentials stay in the human's own session.

## What Aiur is not

- Not a passive observer of agent sessions started elsewhere. Aiur owns the runs
  it dispatches; it does not attach to an external Claude Code or Codex session.
- Not agent-only. Humans can drive the CLI/TUI; the dashboard is read-only by
  default and exposes supported controls when writable mode is configured.
- Not a replacement for the user's assistant. It is typically its counterpart.
- Not a hosted service. Aiur runs on the user's machine, tracker, and tokens.

## What Aiur does

- Polls GitHub Issues, Linear, or an in-memory tracker for work marked for Aiur.
- Creates an isolated workspace for each selected issue.
- Runs a coding agent with a repository-specific YAML config and prompt.
- Coordinates multiple agents through dependency and lifecycle events.
- Shows agent status, logs, progress, and Executor chat in the CLI and dashboard.

## Install

Install the published CLI globally with npm:

```bash
npm install --global aiur-cli
```

The CLI requires Node.js 18 or newer.

The installed command is `aiur`. Aiur also supports a local developer command
(`aiurdev`) when running from a clone of the repository.

## First-run setup

Run the interactive setup wizard from the repository where Aiur should operate:

```bash
cd your-project
aiur init
```

The wizard creates `.aiur/config`, `.aiur/hooks`, and `.aiur/prompt.md` (or can
use a global `~/.aiur/` configuration). It asks for the essentials:

1. The config location (repo-local or global).
2. A tracker and repository (GitHub or Linear).
3. The agent backend (Codex and/or Claude) and permission mode.
4. Agent limits, turn/time limits, polling, and optional prewarming.
5. A `GITHUB_TOKEN` when using GitHub, so Aiur can read issues and manage its
   lifecycle labels.

Review the generated `.aiur/config` and edit the tracker, repository,
credentials, workspace, and agent settings as needed. Configuration is YAML;
Aiur discovers it in this order:

```text
./.aiur/config → ./.aiurconfig → ~/.aiur/config → ~/.aiurconfig
```

When setup is complete, add `agent:todo` to the issues that should be worked
and start Aiur:

```bash
aiur
```

For a headless run, use `aiur --bg`. Useful controls include `aiur status`,
`aiur pause`, `aiur resume`, and `aiur stop`.

## Next steps

- Read the full [Aiur README](https://github.com/its-everdred/aiur/blob/main/src/README.md)
  for configuration, commands, tracker adapters, and troubleshooting.
- Browse starter configs in the [workflow examples](https://github.com/its-everdred/aiur/tree/main/src/examples/workflows).
- Install [opencode](https://opencode.ai) separately if you want Aiur's live
  Executor chat panes.
- Review the [project repository](https://github.com/its-everdred/aiur) and its
  safety warning before using Aiur with production code or credentials.