How Gentic Works: Issues, Agents, and Pull Requests

You create an issue in the web app

Open your project in 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.

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.