# Set up coding agents

iKanban hands work to three coding agents: **Claude**, **Copilot** and **Gemini**. All three run on **your laptop**, in your repository, with your own sign-in to each agent. You don't create API keys or add GitHub secrets.

Set up once per laptop, in the iKanban desktop app. Sessions you start from the web app, the desktop app or Slack all run there.

**Let your coding agent do it:** **Agent settings → Connections → Coding agents → Copy setup prompt**, then paste it into Claude Code, Codex or any coding agent from your repository's folder. It walks through every step below and asks before installing anything. The same prompt is on [Agent Setup Prompt](/docs/ai-chat/agent-setup-prompt). In Claude Code, once This laptop is set up, run `/ikanban-agent-setup`.

## 1. Connect GitHub and link the repository

Agents open pull requests on GitHub, so iKanban needs your repository.

1. Open **Agent settings → Connections → GitHub → Connect** and sign in to GitHub in the popup. If the repository belongs to an organization, click **Grant** next to it before **Authorize**. Without that, GitHub hides the organization's private repositories. If you see **Request**, an organization owner must approve iKanban.
2. In the same dialog, **Configure** lists each team's projects. Click **Link** next to the project agents work in and pick the repository.

The row shows **Needs reconnecting** when GitHub has rejected the connection. Click **Reconnect**.

## 2. Set up this laptop

In the **iKanban desktop app**, open **Agent settings → Connections → This laptop → Set up**:

1. **Repository folder:** choose your clone of the repository.
2. **Where its work is tracked:** pick your team and project.
3. **Optional:** tick **Add two lines to this repository's AGENTS.md** so Codex finds the iKanban setup prompt. AGENTS.md is your file, so this stays off unless you tick it.
4. **Set up and start.**

The app then:

- writes a `.iKanban/` folder into the repository: settings with a new key for this laptop, your team's IDs, and the iKanban skills and prompts;
- keeps the private files out of git;
- links the skills into `.claude/skills` so Claude Code finds them (on Windows it copies them);
- starts the **runner**, the part of the app that picks up agent sessions and runs them here.

The app starts the runner again every time it opens. Every two weeks, and after you update the app, it also refreshes the skills, prompts and README in `.iKanban/`. It never touches your key or team settings. The row shows **runner online** while it runs. If the app is closed, sessions wait as **Queued** and start when you open it.

## 3. Sign in to Claude Code

Claude runs with your Claude Code sign-in, under your Claude subscription.

1. Open a terminal. The iKanban terminal (the panel at the bottom of the desktop app) works.
2. Run `claude auth login` and finish signing in in the browser.
3. Check it: `claude auth status --text` says you're logged in.

Do this once. The runner uses this sign-in for every Claude session.

## 4. Sign in to Copilot and Gemini

They run on your laptop the same way, with your own sign-in:

- **Copilot:** run `copilot login` and approve the device on GitHub. This needs a GitHub Copilot plan.
- **Gemini** runs through Google's **Antigravity CLI** (`agy`), because Gemini CLI's "Login with Google" no longer works for personal accounts.
  1. Install it: `curl -fsSL https://antigravity.google/cli/install.sh | bash`.
  2. Run `agy` once and sign in with a **personal** Google account. A company (Google Workspace) account needs extra Google Cloud setup.
  3. Antigravity can't ask for approval mid-run, so it only runs the commands its rules allow. **Set up** (step 2) adds safe ones: reading files, `git status`/`diff`/`log`, and test, lint and build. It blocks `git push`, `rm -rf` and `sudo`.

**Agent settings → Connections → Coding agents** shows each agent as **Connected** once it's signed in and the runner is online. **Sign in** next to an agent opens the iKanban terminal with the command typed.

If the runner is offline, a session waits until it's back; it never moves to GitHub on its own. To run on GitHub instead, pick **Runs on → GitHub** (Copilot then uses GitHub's Copilot cloud agent, which an organization owner enables for the repository).

## Approvals and hands-off runs

File edits always run on their own. What happens to a **push or a network call** on your laptop is your choice, in **Agent settings → Runners → Risky actions**. It applies from the next run. A new session's **Session settings → Policy** shows the choice that applies to it.

| Choice | What the agent may do without asking |
|---|---|
| **Ask me** (default) | Nothing risky. Pushes and network calls wait for your **Approve** or **Deny** on the session page. |
| **Allow pull requests** (recommended) | Push its own branch and open the pull request. Pushing to main, force pushes, merging and other network calls stay blocked; your repository's checks decide the merge. |
| **Allow everything** (Yolo) | Any push or network call. Fully hands-off, but an agent misled by text in a repository or a web page can reach any site and push anywhere it has access. |
| **Deny** | Pushes and network calls are blocked. The agent works locally. |

A session waiting for you shows **Needs approval** in the Sessions list; open it to answer. The session page header shows the same state as its row in the Sessions list, and both change within about 5 seconds when the session ends, with no reload.

**Runs on GitHub** have no approval step. The agent opens a pull request, often as a draft, and your repository's own workflows review, test and merge it. GitHub's Copilot agent also asks the person who assigned it for a review; that request does not block a merge.

The runner commits with this laptop's git identity. If your global identity is a personal one, set the one you want for the runner's work before you start.

## Keep the laptop awake

A laptop that goes to sleep stops its runner, and a job it was running is lost.

- **While a job runs**, the runner stops the laptop from going to sleep when idle. This needs no setting and no admin rights. On a Mac, `pmset -g assertions` lists it as *iKanban runner: a job is running* while the job lasts; on Windows, `powercfg /requests` lists the power requests apps hold. It ends with the job.
- **Closing the lid, the Apple menu's Sleep, or a low battery still put the laptop to sleep.** Between jobs it sleeps as usual, and new sessions wait as **Queued** until it wakes.
- **To keep it awake even with the lid closed:** in the desktop app, **Agent settings → Runners → This laptop → Keep this laptop awake → Turn on**. The app offers this once, the first time you open the runner card. It asks once for admin rights (your password on a Mac, an admin prompt on Windows). A Mac then never sleeps (`pmset -a disablesleep 1`); on Windows, closing the lid does nothing and the runner also keeps the laptop awake between jobs.
- **It stays on when iKanban is closed or deleted**, until you turn it off. A closed laptop in a bag gets hot and drains its battery.
- **Turn off** asks for admin rights again and restores the setting you had before. If the app is already deleted, run `sudo pmset -a disablesleep 0` on a Mac, or set **Control Panel → Power Options → Choose what closing the lid does** back on Windows.

## Check it works

1. Start a session with a small read-only task, for example *"read README.md and reply with a one-line summary; don't change files"*. Start it from the agent home, or with `@iKanban` in Slack.
2. The session page shows Claude's steps live: files read, commands run, then the answer. In Slack, the thread shows the same progress, then the answer.
3. If it says **Failed**, the reason appears under the activity card. Fix the step it names and try again.

## Troubleshooting

| What you see | Fix |
| --- | --- |
| Session stays **Queued** | Open the iKanban desktop app on the laptop set up in step 2. **Connections → This laptop** should say **runner online**. |
| A session failed or waited while the laptop slept | See [Keep the laptop awake](#keep-the-laptop-awake): turn on **Keep this laptop awake** to keep it awake with the lid closed. |
| **This laptop** says *runner not running* | Open it and click **Start runner**. The log is `~/Library/Logs/com.verbodh.ikanban/runner.log` on a Mac, `%LOCALAPPDATA%\com.verbodh.ikanban\logs\runner.log` on Windows. |
| Claude fails with a sign-in or authentication error | Step 3: run `claude auth login` on that laptop. |
| GitHub said "Not Found" for owner/repo | Step 1: reconnect GitHub and **Grant** the organization, or link the right repository. |
| No repository linked | Step 1: **Link** a repository to the session's project. |
| Copilot or Gemini fails with a sign-in error | Step 4: run `copilot login`, or `agy` and sign in with a personal Google account, on that laptop. |
| Gemini says actions were blocked | Antigravity's rules allow only safe commands (step 4). |
| Every Gemini tool fails with "failed to unmarshal result from hook" | A plugin's hook is broken: `agy plugin list`, then `agy plugin disable <plugin>`. |

**This laptop** needs the iKanban desktop app for macOS or Windows.

Next: [Coding Agents](/docs/ai-chat/coding-agents) for assigning agents from a task, and [Agent Lifecycle](/docs/ai-chat/agent-lifecycle) for what each status means.