Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.agentastic.dev/llms.txt

Use this file to discover all available pages before exploring further.

Agentastic makes it straightforward to hand off a coding task to an AI agent and keep working while it runs. This guide walks you through opening a project, configuring an agent, and reviewing its output — from start to finish.

​
Prerequisites

Before starting, make sure you have the following:
  • Agentastic installed — See the installation guide if you haven’t set it up yet
  • A git repository — Any project with git initialized works
  • An AI agent installed — For example:
    • Claude Code: npm install -g @anthropic-ai/claude-code
    • Hermes Agent: curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

​
Walkthrough

1

Open your project

Launch Agentastic, then press Cmd+O or drag your project folder onto the app window. Select your git repository.You’ll see the Navigator panel on the left showing your project files.
2

Open Agent Home

Agent Home is your control center for launching AI agents. Open it by:
  • Clicking the Home icon in the Navigator sidebar, or
  • Using the keyboard shortcut listed in the Command Palette
You’ll see a prompt card where you can describe your task.
3

Configure your agent

Fill in the configuration fields in Agent Home:
  1. Select your repository — If you have multiple repos open, pick the right one
  2. Choose a base branch — Usually main or master
  3. Select an agent — Pick from the auto-discovered agents (Claude, Codex, Hermes Agent, etc.)
  4. Enter a branch name — A random city name is suggested, or type your own
4

Write your prompt

In the prompt card, describe the task you want the agent to complete. Be specific about what you need, the technologies involved, and any patterns to follow.
Add a user authentication system with:
- Login/logout endpoints
- JWT token handling
- Password hashing with bcrypt
- Basic rate limiting
You can also:
  • Mention files — Type @ to reference specific files for context
  • Attach images — Drag screenshots or click the photo icon
5

Launch the agent

Click the Send button or press Enter.Agentastic will:
  1. Create a new git worktree for your branch
  2. Run your setup script (if configured)
  3. Launch the AI agent in a terminal
  4. Pass your prompt to the agent
The agent now works in its isolated environment. You can keep coding in your main workspace without any interference.
6

Monitor progress

While the agent runs, you have a few options:
  • Watch the terminal — See the agent’s output in real time
  • Switch worktrees — Press Cmd+Option+Down to view the agent’s workspace
  • Keep working — The agent runs in isolation and won’t affect your current work
7

Review the changes

When the agent finishes, inspect what it produced:
  1. Open the Diff Viewer to see exactly what changed
  2. Optionally run Code Review for AI-powered feedback
  3. If you’re satisfied, push the branch and open a pull request:
git push -u origin your-branch-name
gh pr create --title "Add authentication system"
8

Clean up

After merging or discarding the branch, remove the worktree to keep your workspace tidy.From the UI:
  1. Go to Settings > Agents
  2. Right-click the agent’s worktree
  3. Select Remove Agent
From the terminal:
git worktree remove ../your-project-worktrees/branch-name

​
Tips for success

  • Be specific about what you want the agent to build or fix
  • Mention the technologies and patterns you want it to use
  • Reference existing files with @ mentions to give the agent relevant context
  • Begin with single-purpose tasks that have a clear scope
  • Break larger tasks into smaller pieces before handing them to an agent
  • Focused tasks are easier to review and less likely to produce unexpected changes
  • Run Claude for architecture and design decisions
  • Run Codex for boilerplate and repetitive code
  • Each agent works in its own isolated worktree, so there are no conflicts between them
  • Check the diff carefully before merging any agent branch
  • Use the built-in AI code review for a second opinion
  • Test the changes in the agent’s worktree before merging into your main branch

​
Troubleshooting

Agentastic auto-discovers agents that are installed and available in your PATH. If your agent doesn’t appear, verify that the CLI is installed and accessible:
which claude  # Should show the path to the binary
If the command returns nothing, reinstall the agent and ensure your shell’s PATH is configured correctly.
Check the following:
  • The branch name you entered doesn’t already exist in your repository
  • You have write permissions in the project directory
  • Git is properly configured (git config --list to review)
If the agent launches but exits right away, check the terminal output for error messages, then verify:
  • API keys for the agent are set as environment variables
  • The agent supports non-interactive (headless) mode

​
Next steps

Setup and teardown scripts

Automatically install dependencies and configure each agent’s environment when a worktree is created.

Run multiple agents

Learn how to launch and manage several agents in parallel for faster development.

Customize your workflow

Tailor Agentastic’s behavior to match how you and your team work.