Working in a repository

Where it works

Run ivralo inside a git repository. That repository is the workspace: ivralo reads it, edits it and runs its checks, and nothing outside it. Started outside any repository, it works in a folder of its own instead.

ivralo keeps its own state for the workspace in .ivralo/: file history, change records, plans and a code index. It adds the folder to .git/info/exclude, so none of it ends up in a commit.

IVRALO.md: the project's conventions

An IVRALO.md at the root of the repository tells ivralo how the project works. Without one, an AGENTS.md is read instead. A few sections are read by code; everything else is handed to every agent as the project's own instructions.

# Commands

- format: `uv run ruff format --check .`
- lint: `uv run ruff check .`
- types: `uv run mypy`
- test: `uv run pytest -q`

# Conventions

- Dependencies go in through `uv add`, never by hand.
- Never touch `generated/`; it is rebuilt from the schema.

# Commands names the checks ivralo runs to verify a change. Other sections declare where test reports land, which language server to start, and where incident evidence lives. The file can only narrow what ivralo does: nothing that decides a permission reads it.

Trusting a folder

The first time you start ivralo in a folder, it asks whether you trust it. A repository's own declarations run commands on your machine, so they wait for that yes. Until then:

• the commands under # Commands are refused, and no language server starts;
• the folder's own permissions file can only take permissions away;
• its .ivralo/.env is not read, and git writes are refused.

The answer is kept in your ivralo home, never in the folder. ivralo trust records it or takes it back.

The main agent and its team

You talk to one agent, the main agent. It does most of the work itself: it reads the code, runs Python that only reads, changes files through the edit tools, runs the project's checks and commits. It holds what the team as a whole may do, under the same approvals.

It hands work to a specialist only when that is worth it: when a task needs a fresh context, or should run with a narrower grant than its own. The Code Engineer is the specialist for code. Three can work at once by default (IVRALO_CODERS), each beyond the first in its own git worktree, and each worktree's changes come back as a patch that you approve.

Approving changes

Every edit is shown as a diff before it is written, and every call that changes something asks. The dialog gives you a few answers:

A broader answer is simply missing from a call that must always ask. On a high-risk call, Enter rests on no.

/accept-edits lets edits through for the session while shell commands still ask. A run nobody is watching, such as a pipe, a job or a schedule, is granted nothing that would have to ask.

Shell commands

Every shell command is sorted into allow, ask or deny before it runs, and a command made of several parts is judged by its worst one. Read-only commands run, most others ask, and some are always refused:

• programs that reach the network, such as curl, ssh and nc;
• the system's package managers;
• anything that rewrites git history;
• every spelling of git push, and every way of merging or approving a pull request.

You add your own rules to permissions.json, in your home or in the repository's .ivralo/. A deny in either one wins.

Checking a change

ivralo verify runs the commands from # Commands, cheapest first, and stops at the first failure. The agents use the same check before they call a change done. Failures are read from the standard reports your tools already write, such as JUnit and SARIF.

For larger changes, a changeset stages a turn's edits in a separate tree, verifies them there, and then lands them or drops them as one. Your working tree is never left half-written.

Plan mode

For work with several steps, ask for a plan first: press Shift+Tab, type /plan, or run ivralo plan "…". ivralo drafts the plan without touching anything, and you run it, ask for a revision, or drop it. A plan runs in waves, each step starting once the steps it needs have finished. If a step fails, you can roll its wave back to the checkpoint taken before it.

Git

Reading git is free: status, diffs, log, blame and the history of a symbol. Writing asks: staging, committing, making a branch or reverting all go through the same dialog.

The one push ivralo ever makes is for a draft pull request, from a branch it made itself. It always asks first, and it never merges.

Going back

Every file ivralo changes is copied into its history first. ivralo changes lists what each turn changed, and ivralo restore <file> puts a file back as it was. Ctrl+D opens the same list inside a session.