Coding agents
Coding agents take a task-specific instruction and work against a repository. This flow is separate from the in-app AI chat and from external clients connected through MCP.
iKanban works with six coding agents: Claude, Copilot, Antigravity, Codex, OpenCode and Grok. iKanban starts all six on your laptop runner from a task, a session or an automation, each with your own sign-in. Claude, Copilot and Antigravity also run on GitHub. Codex and OpenCode need the desktop app 0.1.28 or later. Grok needs the desktop app 0.1.30 or later.
Codex, OpenCode and Grok on your laptop
| Agent | How it runs | Risky actions |
|---|---|---|
| Codex | codex exec, signed in with codex login (your ChatGPT plan). Codex can't ask mid-run, so it edits in its sandbox: no network, and .git is read-only. When it finishes, the runner commits on a branch named for the task, then asks before git push and gh pr create. | Ask me: you approve the push and the pull request. Allow pull requests: the task branch and its pull request go ahead. Deny: the commit stays on the laptop. Allow everything: Codex runs without its sandbox. |
| OpenCode | opencode acp, with its free models or your own opencode auth login. | Each edit, shell and web call asks iKanban, so Risky actions decides as it does for Claude. |
| Grok | grok agent stdio, signed in with grok login. Install it with curl -fsSL https://x.ai/cli/install.sh | bash; Homebrew's grok is a different program. | Grok starts only when Risky actions is Allow everything, because it doesn't ask before a risky tool runs. With any other mode, iKanban refuses the session when you start it and says why, before any plan or review work runs. Customize items and iKanban's MCP tools don't reach Grok runs yet, and a Grok run loads your laptop's own MCP servers from your Grok config. Grok does not write its own plan or review its own work: Claude or Copilot, signed in on the same laptop, writes the plan and does the review. With neither, the run refuses and says what to do. |
A Wiki run or a security scan with Codex needs Allow everything, because its sandbox has no network; pick another agent otherwise. Customize items and iKanban's MCP tools don't reach OpenCode runs yet, and Customize items don't reach Codex runs. Change Risky actions in Agent settings → Runners.
Codex, Grok, OpenCode and Antigravity do not open their own pull request. When one of their runs leaves a change or a commit, the runner puts it on a branch of the task, pushes that branch and opens the pull request, and asks Risky actions first, as for Codex. The default branch is never pushed. When no pull request is opened, the session says why.
Choosing a model
Once a day the runner asks OpenCode, Grok and Antigravity which models your sign-in offers. Pick one per agent in Agent settings → Git connections → Coding agents. A pick applies from the next run, to the build, the plan and the fix turn. The critic always runs on the agent's default model. If the laptop no longer offers it, the run uses the agent's default and that row says so. Claude, Copilot and Codex use their own default. Free on an OpenCode model comes from OpenCode's own price list; free models are free for a limited time, and some keep your prompts to improve the model.
Before assigning an agent
- Open the task and confirm it belongs to a project with the intended repository connected.
- Confirm the required GitHub connection and coding-agent integration are configured for that repository. First time? Follow Set up coding agents.
- For profile-based agents, confirm the executor profile and provider or CLI access are configured in Settings → Agents and Settings → AI Provider Keys, as applicable.
- Add a clear task description and acceptance criteria. The agent needs enough context to identify the files, expected behavior, and checks.
Assign from a task
- Open the task's comment/agent input.
- Type
@and choose an agent from the suggestion list. Available mentions depend on the configured integration and executor profiles.
- Add the instruction after the mention. For example:
@claude Add server-side validation to the signup handler, return a clear 400 response for invalid email, and add a focused test. - Review the task and instruction, then submit the comment to start the requested work.
Submitting an agent mention is an action: iKanban saves the comment and starts the selected agent. Do not use a real mention just to preview the flow.
Where the run goes
Claude, Copilot, and Antigravity run on your own laptop runner by default, with your own sign-in and the project's first linked repository. The chip over the comment box shows where the run goes:
| Chip | What happens |
|---|---|
| Your laptop | Your laptop runner is online and starts the run. |
| Your laptop · waits for the app | Your runner is offline. The run stays in the queue and starts when you open the iKanban app on your laptop. |
| GitHub | You typed @remote. iKanban opens a GitHub issue and the repository's GitHub workflow runs the agent. |
@local also picks your laptop. One agent runs one laptop run per task at a time; send a follow-up when the first run finishes. The task's Agent Activity card shows on your laptop or on GitHub next to the agent name. Other mentions in the picker use configured executor profiles and can create an iKanban agent attempt for the task.
Follow the run
- Return to the task and open Agent Activity to check the queued/running state and linked GitHub work, when available.
- Open the linked pull request to inspect the branch, changes, and checks.
- Review the diff and CI results. Approve, request changes, or close the pull request according to your repository's review policy.
- Merge only after review. Do not treat an agent's completion message as approval or verification.
For the state transitions and attribution details, see Agent Lifecycle. For a hands-on GitHub task walkthrough, see Working with Coding Agents on GitHub.
Repository workflow files
Claude and Antigravity GitHub Actions behavior depends on the workflow installed in the target repository; Copilot uses its GitHub integration. GitHub runs covers the setup, with iKanban's two workflow files. Workflow permissions, action versions, event text, and secrets must be reviewed for the repository where the workflow will run.
Before enabling an agent workflow:
- Start from the provider's maintained documentation and validate the workflow in a test repository.
- Grant only the permissions the workflow needs; keep credentials in repository secrets and never put secret values in YAML or task text.
- Treat issue titles, descriptions, comments, and review text as untrusted input. Pass event content as data, not interpolated shell source.
- Review every agent-created change and workflow run before merging or granting additional access.
Troubleshooting
| Symptom | Check |
|---|---|
| Agent mention is not suggested | Check the configured executor profiles and integration availability. |
| Comment saved but no run appears | Check that the task's project has a repository connected and that the selected agent is configured. |
| GitHub-backed run is queued or has no pull request | Open the task's Agent Activity links and check the corresponding GitHub issue, pull request, and workflow run. |
| A run failed | Read the provider or workflow logs, fix the underlying configuration or task instructions, then retry deliberately. |
For provider selection in the conversation panel, see In-app AI chat. For tool access from Claude Code, Cursor, or another MCP client, see MCP Usage.