Your First Agent

Launch your first AI coding agent in Agentastic

Prerequisites

Before starting, ensure you have:

  1. Agentastic installed - Download here
  2. A git repository - Any project with git initialized
  3. An AI agent installed - Such as Claude Code (npm install -g @anthropic-ai/claude-code)

Step 1: Open Your Project

  1. Launch Agentastic
  2. Press Cmd+O or drag a folder onto the app
  3. Select your git repository

You'll see the Navigator on the left showing your project files.

Step 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 (check Command Palette for the current binding)

You'll see a prompt card where you can describe your task.

Step 3: Configure Your Agent

In Agent Home:

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

Step 4: Write Your Prompt

In the prompt card, describe what you want the agent to do:

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

Step 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 while you continue working in your main workspace.

Step 6: Monitor Progress

You can:

  • 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 won't interfere with your current work

Step 7: Review the Changes

When the agent finishes:

  1. Open the Diff Viewer to see what changed
  2. Optionally run Code Review for AI feedback
  3. If satisfied, create a pull request:
git push -u origin your-branch-name
gh pr create --title "Add authentication system"

Step 8: Clean Up

After merging (or discarding), remove the worktree:

  1. Go to Settings > Agents
  2. Right-click the agent's worktree
  3. Select Remove Agent

Or from terminal:

git worktree remove ../your-project-worktrees/branch-name

Tips for Success

Write Clear Prompts

  • Be specific about what you want
  • Mention technologies and patterns to use
  • Reference existing code with @ mentions

Start Small

  • Begin with focused, single-purpose tasks
  • Larger tasks work better when broken down

Use Multiple Agents

  • Run Claude for architecture decisions
  • Run Codex for boilerplate code
  • Each works in isolation, no conflicts

Review Before Merging

  • Always check the diff
  • Run AI code review for a second opinion
  • Test the changes in the agent's worktree first

Troubleshooting

Agent Not Found

Ensure the agent CLI is installed and in your PATH:

which claude  # Should show the path

Worktree Creation Failed

Check that:

  • The branch name doesn't already exist
  • You have write permissions
  • Git is properly configured

Agent Exits Immediately

  • Check the terminal output for errors
  • Verify API keys are configured
  • Ensure the agent supports non-interactive mode

Next Steps