Skip to main content
Creating your first Gentic issue takes about five minutes. By the end of this walkthrough you will have an AI coding agent clone your repository, implement a change described entirely in plain text, and open a pull request for you to review — all without writing a single line of code yourself.
1
Confirm the agent worker is running
2
Gentic separates the web interface from the worker process that actually runs AI agents. Before an issue can be picked up, your gentic worker must be online and authenticated.
3
Open a terminal on the machine where you deployed the worker and run:
4
gentic status
5
The output shows whether the worker is running, which API endpoint it is connected to, and the time of its last successful poll. If the worker is stopped, start it with:
6
gentic start
7
If credentials are missing or invalid, re-authenticate first:
8
gentic auth login
9
You will be prompted for your GENTIC_API_URL (for example https://gentic.chat/api/v1) and your GENTIC_API_KEY (your Gentic API key). Once saved, run gentic start again.
10
Add a project in Settings
11
Gentic needs to know which GitHub repository to clone when it runs an agent. If you have not added a project yet, navigate to Settings → Projects and click Add project.
12
Enter the repository in owner/repo format — for example acme-corp/api-server. Gentic prepends the configured GIT_REMOTE_BASE (default: git@github.com:) to build the clone URL, so your worker must have SSH access to that repository. Save the project before moving on.
13
Create a new issue
14
Navigate to Issues → New Issue in the sidebar. Fill in the form fields:
15
  • Project — select the repository you just added.
  • Title — a short, human-readable summary of the task (up to 160 characters).
  • Type — choose Feature, Bug, Feedback, or Idea to categorise the work.
  • Agent — select Claude Code (default) or Codex depending on which agent your worker environment has credentials for.
  • Prompt — the detailed instructions the agent will receive. See the next step for advice on writing an effective prompt.
  • Status — leave this as Draft for now so the agent does not start before you are ready.
    • 16
    Click Create issue to save it.
    17
    Write a great prompt
    18
    The prompt is the single most important input you give the agent. A vague prompt produces vague results; a precise prompt produces precise, reviewable code.
    19
    Follow these patterns for the best results:
    • Be specific about location. Instead of “fix the login bug”, write “In src/auth/login.ts, the validateEmail function does not reject addresses missing an @ symbol.”
    • State acceptance criteria. “The endpoint should return 400 with { "error": "email is required" } when the email field is absent.”
    • Mention the tech stack. “This is a Next.js 14 app using Zod for schema validation and Prisma for database access.”
    • Include file paths when you know them. “Update the schema in prisma/schema.prisma and regenerate the client.”
    • List constraints. “Do not change the public API surface of UserService. All new logic should be in a private helper method.”
    20
    You can always edit the prompt on the issue detail page before you move the issue out of Draft.
    21
    Save as Draft and review
    22
    Staying in Draft status gives you time to re-read the prompt, upload any supporting attachments (screenshots, log files, spec documents), and add issue relations that should complete first. The agent will not run until you explicitly move the issue forward.
    23
    Open the issue you just created and review the prompt in the detail panel. Edit it if anything is unclear or missing.
    24
    Move status to Todo to queue the agent
    25
    When you are satisfied with the prompt, change the issue status to Todo. This is the trigger: Gentic sets run_status = 'queued' and inserts the opening user message. On its next poll cycle (every three seconds by default), the agent worker picks up the issue and begins working.
    26
    You can change the status from the issue detail page using the Status dropdown, or from the home screen using the status badge on the issue card.
    27
    Watch the agent work
    28
    After the status moves to Todo, the issue transitions to In Progress as soon as the worker claims it. The Transcript panel on the issue detail page streams the agent’s output in real time — you can watch it clone the repository, read files, reason about the change, and write code.
    29
    If the issue stays on queued for more than a minute, check that the worker is still running (gentic status) and that it can reach the Gentic API. See the Troubleshooting guide for common causes.
    30
    Review the pull request
    31
    When the agent finishes, the issue status updates to Ready for review (or another terminal state) and a Pull Request URL appears on the issue detail page. Click it to open the PR on GitHub, review the diff, leave comments, and merge when you are happy.
    32
    If the agent did not quite get it right, you can send a follow-up message directly on the issue. Sending a message to a completed issue automatically re-queues the agent so it can continue from where it left off, with the full prior conversation context intact.