> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gentic.chat/llms.txt
> Use this file to discover all available pages before exploring further.

# How Gentic Works: Issues, Agents, and Pull Requests

> Understand Gentic's end-to-end workflow: from creating an issue in the web app to receiving an automated pull request from an AI coding agent.

Gentic connects two things: a web app where your team writes and manages work, and a background worker that turns that work into real code. Understanding how these two parts communicate helps you configure Gentic correctly and troubleshoot issues when something unexpected happens.

## The end-to-end flow

<Steps>
  ### You create an issue in the web app

  Open your project in [gentic.chat](https://gentic.chat) and create a new issue. Every issue has a **title**, a **prompt** (the detailed instructions the agent will follow), and an **agent** selection — either `Claude Code` or `Codex`. You can also attach files: images, text files, and other documents are embedded directly into the agent's first prompt so it has the full context it needs before writing a single line of code.

  New issues start in **Draft** status. A draft is never picked up by the worker, giving you time to iterate on the prompt, add attachments, and set any blocking dependencies before the agent begins.

  ### Moving to Todo queues the issue

  When you change an issue's status from **Draft** to **Todo**, Gentic records your prompt as the first message in the issue's conversation thread and sets `run_status = queued`. These are two separate fields:

  * **`status`** represents where the issue sits in your team's workflow: `Draft`, `Todo`, `In Progress`, or `Done`.
  * **`run_status`** tracks the agent's lifecycle independently: `queued`, `running`, `completed`, `failed`, or `cancelled`.

  Separating the two fields means an issue can be "In Progress" from your team's perspective while the agent has already completed its run, or it can be re-queued for follow-up work without changing its workflow status.

  ### The agent worker polls for queued issues

  Your deployed agent worker runs as a background process on a server you control. It polls the Gentic API on a fixed interval — **3,000 ms by default**, configurable via `POLL_INTERVAL_MS`. On each tick, it calls the API with your `GENTIC_API_KEY`, which the API uses to identify your account and return only issues that belong to your projects.

  <Note>
    The worker is an outbound-only polling process. It never exposes a port or accepts inbound connections. Keep it running on a private server or VM with access to your GitHub repositories — do not expose it as a public web service.
  </Note>

  ### The worker claims the issue and clones the repository

  When the worker finds a queued issue, it claims it (setting `run_status = running`) and clones the project's GitHub repository into a fresh, isolated working directory. The clone target is constructed by prepending `GIT_REMOTE_BASE` (default: `git@github.com:`) to the `owner/repo` slug stored in the project — so a project configured as `acme-corp/backend` is cloned from `git@github.com:acme-corp/backend`.

  Each issue gets its own working directory, so concurrent runs never interfere with one another.

  ### The agent writes code and opens a pull request

  With the repository cloned, the worker spawns the chosen agent through the **Agent Client Protocol (ACP)**:

  * **Claude Code** issues run through `@agentclientprotocol/claude-agent-acp`, using Claude Code credentials already present in the worker environment.
  * **Codex** issues run through `@agentclientprotocol/codex-acp`, which shells out to the `codex` CLI already installed and authenticated in the worker environment.

  The agent receives the issue prompt (plus any attachment content) as its first user message. The worker appends an automatic instruction telling the agent to commit its changes and open a pull request before finishing — you do not need to include this in your prompt.

  As the agent works, its output streams back into the issue's transcript in real time so you can follow along in the web app.

  ### The issue status updates automatically

  When the agent finishes its run, the worker marks `run_status = completed` and the issue appears as done in your web app with a link to the pull request on GitHub. If the agent encounters an unrecoverable error, `run_status` is set to `failed` and any error output is appended to the transcript so you can diagnose what went wrong.

  ### You can send follow-up messages while the agent is running

  The issue transcript is a live conversation. While `run_status = running`, you can type a follow-up message in the web app — for example, to clarify a requirement or redirect the agent. The worker picks up any new messages sent during an active session and delivers them to the agent in the same ACP session without restarting.

  The worker keeps the session open for one full poll interval after the agent goes quiet, so messages sent just as the agent is finishing are still handled in the same run.

  ### Follow-up messages re-queue completed issues

  If you send a message to an issue whose run has already ended — `run_status` is `completed`, `failed`, or `cancelled` — Gentic automatically re-queues it. The worker claims it on the next poll and resumes the **same ACP session** using the stored `session_id`, so the agent picks up exactly where it left off with the full conversation history intact. You do not need to re-enter any context.
</Steps>

## Supported agents

| Agent           | Identifier    | Notes                                                                                                                                                                                                                             |
| --------------- | ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Claude Code** | `claude_code` | Requires Claude credentials (API key or OAuth) present in the worker environment before the worker starts.                                                                                                                        |
| **Codex**       | `codex`       | Requires the Codex CLI installed on the worker machine and authenticated. Set `CODEX_PATH` in the environment if the binary is not on `PATH`. Runs default in `agent-full-access` mode unless `INITIAL_AGENT_MODE` is overridden. |

## Issue and run status reference

| `status`      | Meaning                                                   |
| ------------- | --------------------------------------------------------- |
| `Draft`       | Issue is being written; never picked up by the worker.    |
| `Todo`        | Issue is ready for the agent; sets `run_status = queued`. |
| `In Progress` | Agent run is active (`run_status = running`).             |
| `Done`        | Work is complete; pull request is open on GitHub.         |

| `run_status` | Meaning                                                     |
| ------------ | ----------------------------------------------------------- |
| `queued`     | Waiting to be claimed by the next available worker poll.    |
| `running`    | Worker has claimed the issue and the agent is active.       |
| `completed`  | Agent finished successfully; PR has been opened.            |
| `failed`     | Agent encountered an error; see the transcript for details. |
| `cancelled`  | Run was cancelled manually before completion.               |

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Follow a step-by-step guide from signup to your first pull request.
  </Card>

  <Card title="Agent Worker Setup" icon="server" href="/agent/overview">
    Deploy, configure, and manage the background worker process.
  </Card>
</CardGroup>