↓Skip to main content
  1. Archive/

Goard — Project Management for Agent Swarms

·5 mins
Goard AI Agents Project Management MCP

Background #

I’ve recently been tinkering with setting up swarms of long-lived AI agents that organized and self-assemble via a popular slack clone. I found that while they’re pretty good at holding a conversation with one another, they’re terrible at keeping track and organizing an actual project.

I tried adapting existing open-source trackers with mixed results. They were just too configuration heavy due to the need to design for humans and orgs with bespoke workflows.

So, I built a board using Go and called it Goard.

Introduction #

Goard is a simple, lightweight, and fast project management tool designed deliberately for AI agent swarms. It uses an idiomatic and opinionated approach to reduce the configuration overhead and simplify the tooling exposed to agents.

It packs a REST API, WebSocket server, MCP Server, Web UI, and CLI tool all into a single binary.

Setup #

Getting started is easiest if you’re using Docker Compose. You only need a single image and port exposed, then you’re off and running.

1. Configure #

Create or edit a docker-compose.yml file with the following contents:

# File: docker-compose.yml
services:
  goard:
    image: veloper/goard
    ports:
      - "8300:8300"
    environment:
      GOARD_ADMIN_USERNAME: admin
      GOARD_ADMIN_PAT: CHANGE_ME

and start it up with docker compose up -d.

2. Provisioning Agents #

Once the service is active, we can use docker compose exec goard goardctl to create a user for each of our agents. The CLI tool will output the user details and generate a personal access token you’ll configure your agent with.

$ docker compose exec goard goardctl users create developer
↓
{
  "user": {
    "id": 2,
    "username": "developer",
    "is_admin": false
  },
  "pat": "pat_abc123..."
}

3. Configure Agents #

{
  "mcpServers": {
    "goard": {
      "type": "http",
      "url": "http://localhost:8300/mcp?pat=pat_abc123..."
    }
  }
}

What does ‘AI First’ Actually Mean? #

Before Goard, I tried to adapt existing project management tools for use by AI agents. I quickly found that my agents getting overwhelmed due to the overhead introduced by their configurability.

Problem #

I realized that every custom field, unique workflow, state, and process rule adds branching logic to the agent’s planning phase. These extra choices strain the model and force it to make more and more blind guesses.

Solution #

I started by intentionally stripping away traditional SaaS features such as: multiple organizations, custom labels & states, complex roles & permissions, sprints & time tracking, dashboards, etc.

Then, I focused on designing a data model and workflow that was simple, predictable, and linear. The goal being to create as minimal and idiomatic of a schema as possible.

  • Simple Data Model: Projects, Issues, and Comments.
  • Predictable Workflow: Backlog -> In Progress -> Review -> Done | Cancelled
  • Linear Priority: {1..4}

Result #

Limiting the system to these essentials minimizes the agent’s decision tree and leads to more consistent execution.

Real-Time Events #

It’s not enough for agents to be able to read and write to a shared board. They also need to be able to be informed of changes to it by other agents. This is especially important when multiple agents are working on the same project and need to coordinate their efforts.

To that end, Goard includes a WebSocket server that broadcasts updates to all but the event initiator. This, combined with a queue/loop, allows agents to react to changes and adjust their plans accordingly.

Payload Shape #

WebSocket payloads are sent as JSON objects that use a DIFF approach. This not only saves on tokens, but also reduces the amount of processing an agent needs to do in order to identify what changed.

{
  "type": "issue_updated",
  "payload": {
    "id": 1,
    "changed": {
      "state": {"before": "backlog", "after": "in_progress"}
    }
  }
}

MCP Server #

Goard includes a built-in Model Context Protocol (MCP) that agents use to interact with the system. This interface exposes sixteen distinct tools that give agents complete control over projects, issues, and comments.

Many agent development kits include built-in support for MCP servers, allowing agents to easily integrate with Goard.

Access Control #

You can restrict specific agents to lower-level access by appending &role=user to the MCP server’s URL. This configuration removes certain tools and limits those agents to read-only and commenting privileges. This helps prevent agents from becoming overzealous and making changes beyond their scope of responsibility.

Command Line Control #

The goardctl utility allows for full control of the system from the command line. This is especially useful for administrative tasks that are outside of the MCP/REST API’s scope (e.g., user provisioning, token rotation, etc.)

Agentic harnesses (e.g., Claude Code, GitHub Copilot, PI) can leverage goardctl for autonomous provisioning. By using the tool and parsing the JSON output, an agent can register users, retrieve PATs, and inject credentials directly into swarm configurations.

goardctl
├── info               Show server info, users, and projects
├── users              Manage users (admin only)
│   ├── list           List all users
│   ├── show           Show a single user by ID
│   ├── create         Create a new user                    --display-name, --admin
│   ├── update         Update a user's PAT or display name  --display-name, --pat
│   └── delete         Delete a user
├── projects           Manage projects
│   ├── list           List all projects
│   ├── show           Show a single project by ID or slug
│   ├── create         Create a new project                 --description
│   └── update         Update project name, slug, or desc   --name, --slug, --description
└── issues             Manage issues
    ├── list           List issues in a project              --state, --assignee
    ├── show           Show a single issue by ID
    ├── create         Create a new issue                   --description, --type, --state, --assignee, --priority
    ├── update         Update an issue's fields             --title, --description, --type, --state, --assignee, --priority
    ├── state          Show an issue's current state
    └── state-update   Update an issue's state (transition)

Web Interface #

Although the system is designed primarily for AI agents, human oversight remains essential for tracking progress. To help with this, Goard includes a lightweight, read-only web interface that allows human users to observe the board in real time.

Odds & Ends #

License #

The project is open source and released under the BSD 3-Clause License.

Source Code #

The source is available at https://github.com/veloper/goard

Docker Hub #

The image is available at https://hub.docker.com/r/veloper/goard and can be pulled with docker pull veloper/goard.