Start here
Complete your first task
Set up alterac.ai locally in an existing Git project, run one small task, review the result, and mark it done.
Use alterac.ai to complete one small, useful change in your existing local Git project and take it from Backlog to Done. Plan for about 20 minutes of active setup and review time; your coding agent's execution time is separate and can vary.
Before you begin, confirm that:
- You have an account with access to an existing organization and project.
- You have a local checkout of the Git project you want to change.
- You have downloaded and installed the CLI.
- You have installed and signed in to a compatible coding-agent program. Use its provider's setup instructions, such as Codex CLI (external site) or Claude Code (external site).
Complete any missing prerequisite, then return here to run your first task.
From the root of the existing local Git project you want an agent to change, run:
alterac-ai init
Sign in if prompted, select the project, choose how local coding-agent commands are approved, and select the root instruction file to manage. The default approval mode asks when a command is first used or changes. Coding-agent commands run with your local permissions, so read the command before approving it.
Success ends with:
alterac.ai is ready for use. Start listening for tasks by running alterac-ai listen.
If you do not see that message, finish the prompt or resolve the access problem it reports. Do not manually create .alterac-ai files; rerun alterac-ai init after access or setup is corrected.
Now configure a coding agent for the project. Create an enabled definition using the program you installed, then return here. The configuration guide uses the initialized repository from the previous step.
In the same local project, start the local listener and leave this terminal open:
alterac-ai listen
The listener waits for work you queue in the selected project. It may ask you to approve the first command, or a changed command, before it starts the agent. Approve only a command you recognize; selecting a coding agent in the application does not bypass local approval.
The listener is ready when it remains running without an error. If it reports missing local-project setup or authentication, run alterac-ai init again in this checkout. Keep this terminal available until the task reaches Reviewing.
In the alterac.ai project, open Tasks and select Create task. Use a narrow improvement that matters in your local project. For example, adapt this task to a small piece of existing documentation:
| Field | Value |
|---|---|
| Task title | Clarify the recovery step in the contributor guide |
| Task details | ## Goal followed by the exact section to clarify and the expected reader outcome. ## Acceptance criteria followed by one or two observable checks. |
| Mass | 3 |
Keep the task specific enough to review in one sitting. Do not use a hello-world change or a broad refactor. Select Create task.
Mass is the expected difficulty of reviewing the completed work, not a traditional Agile weight or estimate of how long implementation will take. For this small task, use 3.
You return to the task list and the new task is in Backlog. If the task is not there, check that you are in the intended organization and project, then create it again with a title and task details. For more guidance on task details, Mass, labels, dependencies, assignment, editing, or deletion, read Create and edit a task.
Open the task, select Queue, choose the enabled coding agent, and select Queue task. The task changes to Queued while the listener is waiting for or launching the command. After local approval and launch, it changes to Agent working.
Agent execution time is unpredictable. You can continue other work while the listener and agent run, but leave the listener terminal open. If the task remains Queued, look at that terminal for an approval prompt or error. If no coding agent is available in the queue dialog, return to coding-agent setup. Queue a task explains listener approval, dependencies, and queue recovery in more detail.
When the agent submits its result, the task changes to Reviewing. This is the handoff point, not an automatic completion.
Open Review from the task. Read the change summary, follow any code-review link, and inspect the local Git changes using the proof the agent supplied. Confirm the result meets the task details and acceptance criteria.
When it does, select Mark done. The task state becomes Done, and its review history remains available from the task.
If it needs another pass, use Request follow-up work to preserve your review comments for a new run, or Start fresh to create a new run without continuing the current review feedback. See review completed work for the full review flow.
You have completed the direct task workflow: Backlog, Queued, Agent working, Reviewing, and Done. Next, learn when to plan work with Task Builder, organize tasks, add general task context, or read review history. You can also refine coding-agent setup or manage organizations and projects.