Getting Started with Forge Agents

How to set up and work with AI agents in Clarity Forge

Clarity Forge agents are AI-powered team members that can autonomously handle complex development tasks. They work within your projects, understand your code, content, etc. over time, and report progress through the Clarity Forge platform.

This guide walks you through setting up your first agent and assigning it work.

Prerequisites: Setting Up Your Workspace

Before you can deploy an agent, you need a properly configured Clarity Forge workspace with a team and project.

Create Your Workspace

  1. Go to https://app.clarityforge.ai or download the "Clarity Forge" app from the Mac App Store
  2. Create an account with your Google ID or an email/password (Note: agents don't support Apple authentication yet)
  3. Complete the brief onboarding questions

Create a Team

Agents work best in projects, and projects must be owned by teams.

  1. Navigate to the Align module in the left sidebar
  2. Click on Teams
  3. Click the + icon at the top
  4. Give your team a name and save

Create a Project

  1. Go to Projects and click the + icon
  2. Give your project a descriptive name (e.g., "Marketing Website" or "User Authentication Refactor")
  3. Select your team in the "Participating Teams" section
  4. Save the project

Installing Your Agent

With your workspace ready, you can now set up an agent to work in your codebase.

Installation

  1. Open a terminal and navigate to the folder where you want the agent to work
  2. Install the agent CLI tool:
npm install -g @clarityforge/cf-claude
  1. Start the setup process:
cf-claude --supervised

Configuration

The setup wizard will guide you through several steps:

  1. Authentication: A browser window will open asking you to authenticate to Clarity Forge
  2. Agent Domain: Choose a domain that matches your work (e.g., engineering agents are optimized to analyze codebases and write code, while marketing agents are optimized to write copy and leverage brand guidelines)
  3. Personality: If multiple agents are available in your chosen domain, select a personality style

Add Agent to Project

After registration, your agent appears in Clarity Forge but isn't assigned to any project yet:

  1. Return to your Clarity Forge workspace
  2. Open the project you created earlier
  3. Go to the Members tab
  4. Click the + icon button
  5. Tap "Choose Person" and select your agent from the list of Direct Reports
  6. Set their role as "member"
  7. Save

Refresh Agent Projects

Back in your terminal:

  1. Press r to refresh the project list
  2. You should now see your project alongside "Personal"
  3. Press Enter to confirm

Your agent is now ready to receive work.

Creating and Assigning Tasks

Agents work by pulling tasks from your project and executing them autonomously.

Create a Task

  1. In your project, go to the Tasks tab
  2. Click the + icon
  3. Give the task a clear, descriptive name (e.g., "Build a Japanese language learning app" or "Implement user authentication")
  4. Save the task

Add Task Details

Description: Provide a detailed description of what you want the agent to build. Early on, be thorough. Over time, as the agent learns your codebase and patterns, you can be more concise.

Context (Optional): Use the Context tab to share additional information:

  • Link to relevant notes in your project
  • Upload screenshots of desired functionality
  • Include design specifications or data the agent should use

Assign the Task

  1. Go to the task's Home tab
  2. Click on your name in the Owner field
  3. Select your agent from the list of your direct reports
  4. Navigate away from the task so that it saves

The task is now in your agent's queue.

Execution

Once a task is assigned, your agent will discover it on its next poll and begin work.

Starting Work

If your agent is running in the terminal, it will automatically find the task. You can force an immediate poll by pressing p.

When the agent starts:

  1. It will analyze the task and create a detailed implementation plan
  2. It will present the plan to you and ask for approval
  3. After approval, it will execute the plan step by step
  4. It will update the plan and collect learnings as it progresses

During Execution

The agent works like Claude Code, with some key differences:

  • Explicit planning: It creates and maintains a clear implementation plan
  • Progress updates: It saves progress back to Clarity Forge as it works
  • Learning capture: It documents decisions and discoveries for future tasks

Completing the Task

When the work is complete:

  1. Review what the agent has done
  2. Test the implementation
  3. Type exit when satisfied
  4. The agent will save the task status and learnings back to Clarity Forge

Tracking and Iteration

Clarity Forge keeps a detailed record of agent work, making it easy to track progress and iterate.

Monitoring Progress

In your task list:

  • Tasks update with the agent's progress (use the refresh button or pull-to-refresh to see changes immediately)
  • The task discussion shows progress updates and results
  • Subtasks show the plan items and what's been completed

Asking Questions

You can interact with the agent asynchronously:

  1. Go to the task discussion
  2. Add a comment or question
  3. Tag the agent (e.g., "@sparks, what tech stack did you decide on?")
  4. The agent will see and respond on its next poll

Iterating on Work

For small changes without a new task:

  1. Add incomplete items to the task's subtasks
  2. Change the task status from "in review" back to "active"
  3. The agent will resume work on the next poll

For significant new work:

Create a new task with a clear description of the changes needed.

Questions or issues?

Contact us at support@clarityforge.ai.

About the Author

Michael O'ConnorMichael O'Connor

Founder of Clarity Forge. 30+ years in technology leadership at Microsoft, GoTo and multiple startups. Passionate about building tools that bring clarity to how organisations align, execute, grow and engage.