DocsGet Started
View as Markdown

Your First Agent

Launch, monitor, review, and complete one isolated coding-agent task

The best first task is useful, narrow, and easy to verify. Avoid handing a new workflow an entire feature before you have seen one task move from prompt to pull request.

Before you start#

You need:

  • Agentastic installed on macOS 14 or later
  • A git repository with a clean base branch
  • At least one signed-in provider CLI

Confirm the provider works from a regular terminal before debugging it inside another tool:

bash
which claude claude --version # or which codex codex --version

Browse Supported Agents if you need an install command.

Choose a bounded task#

Good first tasks have a clear finish line:

  • Fix one failing test.
  • Add one endpoint and focused coverage.
  • Update a component to match an attached screenshot.
  • Explain and remove one deprecation warning.

Write the prompt with an outcome, constraints, and verification:

text
Fix the failing checkout total test. Keep the current rounding behavior for USD and EUR. Do not change the public API. Run the focused checkout test file and summarize the root cause when finished.

Create the agent#

  1. Open the repository in Agentastic.
  2. Open Agent Home.
  3. Select the repository and base branch.
  4. Choose the provider CLI.
  5. Keep Worktree selected for isolation.
  6. Give the task a recognizable name, such as fix-checkout-total.
  7. Send the prompt.

Agentastic creates the branch and checkout, runs configured setup commands, starts a native terminal, and delivers the initial prompt using that provider's supported interface.

Monitor without hovering#

The Agents navigator is the task queue. Use it to see which sessions are running, waiting, ready for review, or already associated with a pull request.

Open the task when you need to:

  • Read the terminal output.
  • Answer a permission or clarification prompt.
  • Inspect changed files.
  • Start the app and preview the worktree in the browser.
  • Send a follow-up with a missed constraint.

Because the task is in another worktree, you can continue editing the main checkout or launch other independent tasks.

Verify the result#

Do not treat a stopped agent as a finished change. Check the evidence:

  1. Read the agent's summary and test output.
  2. Open the built-in diff and inspect every changed file.
  3. Run the focused verification command yourself when the change is important.
  4. Preview UI work in the worktree's browser.
  5. Optionally run a separate code-review agent.

If something is missing, send a precise follow-up in the same session:

text
The implementation is good, but the regression case for a zero-value coupon is missing. Add that test and rerun the same focused suite.

Ship or discard#

When the result is ready, use source control or the Inspector to commit, push, and open a pull request. The branch is ordinary git, so command-line workflows work too:

bash
git push -u origin fix-checkout-total gh pr create --fill

After merge, archive the task if you want to keep it visible, or remove its worktree from the Agents navigator. Discarding a worktree does not change the base branch.

Launch the same workflow from a shell#

With the system-wide dev CLI installed:

bash
dev agent create \ --repo ~/src/store \ --agent codex \ --name fix-checkout-total \ --prompt "Fix the failing checkout total test and run the focused suite."

Check status or send more direction without focusing the app:

bash
dev --json agents dev tail <terminal_id> 80 dev send <terminal_id> "Add the zero-value coupon regression case."

Next steps#