# Agent-native

Most tools were built for a person at a screen and later given an API for
agents. Acahti starts from the other side: an agent should be able to do any
job a teammate does on it, as itself, with the same rules, and a person should
be able to see and steer that work.

## Agents are members

- **Their own identity.** An agent connects with its person's OAuth sign-in or
  personal Access Token. Its commits carry the Git identity the instance hands
  out in `whoami`, and its pipelines run as the head commit's author.
- **Named in the work.** Projects list agents as members next to people. A todo
  has a human owner and can name an agent as its delegate (`delegate_login`).
- **Context before code.** `project_context` briefs an agent on a project's
  open tasks, decisions and open iterations in one call, and `planning_brief`
  gives an iteration's scope, risks and capacity.

## One catalog for every surface

The web app, MCP at `/mcp`, the REST API at `/acahti/v1` and the `acahti` CLI
are clients of one operation catalog. What a button does in the app, an agent
can call by name, with the same permissions.

<ol class="planes" aria-label="One catalog behind every surface">
<li><b>Surfaces</b><ul><li>Web app</li><li>MCP<small>/mcp</small></li><li>REST<small>/acahti/v1</small></li><li>CLI<small>acahti</small></li><li>Aidy<small>in the app</small></li></ul></li>
<li><b>Operations</b><ul class="bar"><li>One catalog<small>the same permissions and results for every caller</small></li></ul></li>
</ol>

Install the skill once from this site and connect it to any instance; everything
specific to the instance comes from `whoami`. See
[Connect an agent](agents.md) and [MCP tools](mcp.md).

## Results made for agents

An agent pays for every token it reads, so results are shaped for it:

- `checks_wait` returns the state of a commit's checks in one snapshot, to poll
  until they finish.
- `pipeline_log` without a step returns only the failed steps' logs, optionally
  just their last lines.
- `inbox` lists the latest failed or blocked run of each repository and the open
  pull requests whose head pipeline is green.
- Every operation is described with its arguments in [MCP tools](mcp.md), and
  `acahti mcp tools` lists them from a shell.

```text
repo_get → branch_list → edit and push
                           ↓
                     checks_wait
                      ↙       ↘
           failed-step logs    green checks
                ↓                   ↓
            fix / rerun       review → pr_merge
```

## Rules that hold for everyone

Agents get real write access, so the rules live in the instance:

- `pr_merge` succeeds only when the newest pipeline on the pull request's head is
  green. A green pipeline means the configured checks passed.
- Pipeline secrets are written once and never come back out, to people or agents.
- Gated deploys wait for a person (`deploy_approve`).
- Aidy, the agent inside the app, shows each change it wants to make and waits
  for your confirmation.

## People stay in the loop

People see agent work where they see their own: on the Board, in Track, in
notifications and on each pull request and pipeline. Track shows which stage
each flow has reached and how long it has been there, so a stuck agent is as
visible as a stuck teammate. See [Track is the mainline](mainline.md).