An experimental harness for coding agents. It is not stable, it comes with no guarantee of any kind, and it changes all the time.
This is a personal project, not a product. Commands, settings and file formats change without notice, and whatever is described here may be changed or removed at any time. Its security has not been audited. If you want a coding agent to rely on, use an established one instead.
iq is short for ironquill: iron, as rust is iron's, for it is written in Rust; a quill, for what it writes.
iq runs coding agents in the terminal, on your machine. For now, the models answer through Requesty's router alone; other providers are meant to come later. A lead agent takes your request and may start other agents, with the roles, models and effort it chooses; they write to each other and to you on a shared board, and each chat may work in a git worktree of its own. iq is the harness around them: the gate, the sandbox, the board and the costs. The models do the work.
Three principles hold it together:
- Security is the foundation, not a layer. Everything an agent does goes through one gate, and every command runs in the operating system's sandbox.
- Your skills say how the work is done. iq ships no method of its own. Which team to start for a kind of work, with which roles and models, how its agents work together and review each other: you write it in your skills, and you find your own formula. iq makes it easy to follow: agents that start others, messages between them, a worktree per chat, every step in view.
- Conversations kept light. Past a size the settings give, an agent's old tool results (files read, test output) are set apart at once, each replaced by a line saying what it was, which the agent may read again whole; you see when it happens.
- Every cost is in view. Each call to a model says what it cost, summed by model, by kind of work and over time, and while a turn runs, what each of its agents spent in it. iq never holds an agent back to save money: you see what it spends, and you decide, down to the only models iq may start, for you and every agent, and, when you set it, how much a turn may spend before you are asked whether it goes on. Each choice of a model, yours or an agent's, is written down with who made it and how.
This is how iq is designed to hold, and which part of its code holds what: the code is split into crates, libraries each with one responsibility. It is a design, not a guarantee.
- One gate (the
iq-gatecrate). Reading or writing a file, running a command, reaching the network: every action an agent asks for is judged there, then allowed, asked of you, or refused. Only the gate can issue the permit an action needs, so the compiler itself refuses a way around it. Every decision is written to an audit log before the action is taken, and the rules that judge commands live in iq's own folder, never in the project, which commands can write. - The operating system's sandbox (the
iq-gatecrate). Commands run confined by the kernel: Landlock and seccomp on Linux, Seatbelt on macOS; other systems refuse commands until their sandbox is written. A command writes only where the work is (and in its chat's folder of scratch, outside the project, for its logs and snapshots), always reaches localhost (on Linux, through a network of the sandbox's own), and reaches the internet only when a rule gives it (fetching packages and sources), when you allow it, or once you opened it for every command. No command has your terminal, sandboxed or not: what would ask there (ssh, sudo, a passphrase) fails at once, and one still waiting for an answer nobody can give is stopped. The git hooks a command leaves behind are put back. - Secrets never reach a model. Files that hold secrets are refused, the secrets of your environment are kept out of commands, and what commands print is cleared of the project's own. API keys come from the environment only.
- The machine itself. What needs your machine outside the sandbox (the container daemon, a cluster, a forge's or a cloud's command line, with your credentials) runs there only once approved, as you would run it yourself.
- What others share waits for you. Publishing, or anything that changes what other people see, is always yours to approve.
To report a vulnerability, please use the repository's private vulnerability reporting rather than a public issue.
By default, every question the gate asks comes to you. With the autopilot on, a reviewing model answers in your place, within bounds it cannot widen:
- it answers what stays within the sandbox and, when you let it, what only reaches the internet and what runs on the machine itself;
- it follows a policy you write yourself, as one of your skills: read again at each decision, kept outside the project so that no command can rewrite it, and never shown to the agents it judges;
- it sees the agent's task, your latest request and the agent's last actions, so that each decision rests on what is happening, and what the agent wrote just before, as its own claim, never as your word;
- publishing, changing what others share, files outside the project and secrets are never its to allow, and after a few refusals in a row the agent's next action comes back to you.
Rules and the reviewer only spare you questions: they widen nothing you did not allow.
- Rules. The agents follow the project's own rules (its
AGENTS.md, and the rule files many projects already keep for their agents) and the rules you give every project. - Skills. Markdown files of yours, each for a kind of work: every agent, one another agent started too, reads one before the work it serves, so that an agent starting others chooses them as you wrote. The autopilot's policy is one of them, kept for the reviewer alone.
- Notes. Each project has notes the agents keep for themselves, found again from the same repository on another machine.
- Sync. Your settings, your command rules, the rules and skills kept in iq's own folder (the autopilot's policy among them), the projects' notes, and any file of your home you list can be kept in a private git repository of yours, on GitHub or any other git host, and are put back on a new machine. What a sync would send is shown line by line for you to approve, unless you let it go on its own. What holds secrets is never kept, and a new machine takes what is there before it sends anything. Git does it with the machine's own credentials: nothing goes anywhere but the repository you named.
- What stays on the machine. The chats and their folders of scratch, the journal of tasks and costs, the observations and the audit log: they are not synced.
iq can be extended by plugins: programs of their own, started only when your settings name them, which speak with iq over a small protocol of JSON lines (the iq-plugin crate). A plugin may add commands, show a line of status, and give the commands run in a place the variables they need there. What only some projects need (containers, a cluster, a cloud) belongs in a plugin, while iq keeps the generic part. A plugin runs on your machine as you and answers to you alone: no agent can start one or speak to it, what it gives is written to the audit log, and the gate refuses the variables its sandbox rests on. No plugin is published yet.
The agents can use the tools of the MCP servers your settings declare, by an address or a command: no agent can add one. Each call goes through the gate: a tool its server says only reads is judged as reaching the internet, any other waits for you, since it may change what the server keeps, which others may share. A server that asks for OAuth gets your consent in the browser, its grant kept in iq's own folder for that server's address alone, readable by you only and never synced; what a header carries is read from your environment, never written in the settings.
A Rust workspace whose crate graph enforces the separation: the agents never depend on the providers, the interface's state is tested without a terminal, and nothing reaches the machine without the gate's permit. AGENTS.md describes each crate and the rules every agent working on iq follows, iq's own among them.
export REQUESTY_API_KEY=... # Requesty's key, read from the environment only
iq # runs in the terminal
iq do "..." # hands a task to the agents at once
iq --helpiq runs on Linux and macOS, the systems its sandbox is written for. Each release carries the binary built for Linux (x86_64) and macOS (Apple Silicon), with its checksum; its notes say what it needs to run, and CHANGELOG.md what changed. To build it from the source instead:
cargo install --path . # builds the iq binary into ~/.cargo/bin
scripts/check.sh # formatting, lints, docs, tests, dependency audit
git config core.hooksPath .githooks # run those checks before every commitAn optional part of iq, built only when asked for, to try a new model on your own kind of work without a second copy of iq: frozen exercises are given to candidate models, each run in a folder of its own, checked by hidden tests a command runs, then graded blind by one grader, always the same so that grades compare, and summed into what each candidate does and costs. Like the rest, it may change or go at any time.
cargo install --path . --features assay
iq assay # what its folder holds: the exercises, where each stands, the results
iq assay freeze <exercise> # freezes an exercise, once its check fails on start/ and passes on the reference
iq assay run <exercise | kind | all> <candidates...> [--times N] # runs, checks and grades them
iq assay grade [<exercise | kind | all>] # grades with the current grader what it has not graded yetA candidate is a model of the provider, or a team: pair: writer + reviewer, lead: lead + cheaper, debate: a + b. A run or a grading says what it should cost and asks before anything is spent.
The assay keeps a folder of its own, never iq's: $XDG_DATA_HOME/iq-assay (~/.local/share/iq-assay by default), or the one IQ_ASSAY_HOME names. Its README.md says how an exercise is written. Its settings are in settings.toml there: grader (needed to run and to grade), grader_effort, candidates (models, teams, or candidates by name), effort (the candidates'), reference (the model the others are measured against), parallel (runs at once) and base_url. A key it does not read is said and left aside. The provider's key comes from REQUESTY_API_KEY, as iq's does. Its audit log and the calls it was billed are kept in the same folder. The exercises and runs an older iq kept in ~/.local/share/iq/assay are read as they are, once moved there.
None of this data ships with the program: each install fetches it for its own use and says where it comes from.
- Model lists, prices and context windows for the provider's models come from the provider itself.
MIT