← Back to home

Quick Start

This guide walks you through creating your first automated task run — from project setup to a pull request appearing in your repository.

1. Add a Project

Navigate to the Projects page and click New Project.

  • Name — A label for the project (e.g., "My API")
  • Git URL — The clone URL of your repository (HTTPS or SSH)
  • Git Provider — Select GitHub, GitLab, Gitea, or Bitbucket
  • Default Branch — Usually main or master

AgenticKode parses the git URL automatically to detect the provider, owner, and repository name.

Project Instructions (Optional)

On the project's Instructions tab, you can add context that gets injected into every AI prompt:

  • Global instructions — Applied to all phases (e.g., "Use Python 3.12, follow PEP 8")
  • Phase-specific instructions — Override for individual phases (e.g., custom review criteria)

2. Configure an Agent

Go to the Agents page and verify at least one of the three supported agents is configured:

  • Claude CLI — Needs ANTHROPIC_API_KEY in your environment. The worker auto-installs the CLI on workspace servers.
  • Codex — OpenAI's Codex CLI. Authenticate via the per-server login flow (Workspace Servers → server card → Agents → Login).
  • OpenCode — Self-hostable open-source coding agent. Same per-server login flow.

Each agent can have custom environment variables and CLI flags set from the Agents page.

3. Set Up a Workspace Server

AgenticKode executes tasks on remote workspace servers via SSH. Go to Workspace Servers and add your server:

  • Host — IP or hostname of the server
  • Port — SSH port (default 22)
  • SSH Key — Select or generate an SSH key pair from Settings

Click Test Connection to verify SSH access, then Setup to install dependencies and create the worker user.

See the Workspace Servers guide for details on worker user isolation and agent discovery.

4. Create a Run

Navigate to the Dashboard and click New Run.

  • Project — Select the project you created
  • Task Description — Describe the task in natural language (e.g., "Add input validation to the user registration endpoint")
  • Workspace Server — Select the server to execute on
  • Agent — Choose which AI agent to use, or leave the default

Advanced Options

  • Trigger Mode — auto runs all steps automatically. wait_for_approval pauses at the approval step.
  • Per-step agent override — Pin a specific agent (claude, codex, opencode) to an individual step.

Click Start Run.

5. Monitor Progress

The Run Detail page shows:

  • Current step — Where the run is right now
  • Live Logs — Real-time WebSocket log streaming from the worker
  • SSH Terminal — Direct terminal access to the workspace server (xterm.js)

A coding run is a single flow prompt (implement) — one agent call that takes the task end-to-end:

  1. workspace_setup — Clones the repo (idempotent). Forces workspace_strategy=worktree so concurrent runs on the same project stay isolated under <base>/.worktrees/run-<id>-<ts>.
  2. init — Creates the feature branch.
  3. agent — A single agent invocation given the flow prompt + fetched repo/issue context. The prompt tells the agent to do the work, commit, push, and open a PR/MR before finishing.
  4. finalization — Cleans up the worktree, posts any review comment, marks the run complete.

PR-review runs use the pr_review flow prompt instead — it fetches the PR diff and posts a review comment (no checkout). See Autonomous Mode.

6. Review and Approve

When the run reaches the Approval phase:

  1. A pull request is created in your repository
  2. The run pauses and shows Approve and Reject buttons
  3. Review the PR diff in your git provider
  4. Click Approve to merge, or Reject to discard

After approval, the finalization phase sends notifications and marks the run complete.

7. Automate with Webhooks

Instead of creating runs manually, configure webhooks so that new issues automatically trigger runs:

  • GitHub, GitLab, and Gitea issue events
  • Plane issue events

See the Webhook Setup guide for configuration details.

Next Steps