Frequently Asked Questions

Common questions and answers about Codemus.

Installation

What are the system requirements?

Codemus requires macOS 14.0 (Sonoma) or later, Apple Silicon (M1/M2/M3), 8GB RAM minimum (16GB recommended), and the Claude Code CLI installed.

How do I install Claude Code CLI?

Important: Claude Code CLI requires an active Claude subscription. You must have a valid Claude account with an active subscription before you can use Codemus.

Once you have a subscription:

Visit claude.ai/code to download and install Claude Code CLI
Make sure the CLI is in your PATH or configure the path in Codemus Settings → CLI
Codemus will verify that Claude Code CLI is accessible and properly configured

Do I need a Claude subscription to use Codemus?

Yes, a Claude subscription is required. Codemus uses Claude Code CLI as its AI inference backend, and Claude Code CLI requires an active Claude subscription. Without a valid subscription, Codemus will not be able to function.

What happens if I don't have Claude Code CLI installed?

Codemus will not function without Claude Code CLI. The application will show an error and guide you to install Claude Code CLI. You must have both Claude Code CLI installed and an active Claude subscription.

Can I use Codemus on Intel Macs?

No, Codemus requires Apple Silicon (M1, M2, M3, or later) for optimal performance with AI operations.

Agents & AI

What is a PM Agent?

The Project Manager (PM) Agent is an AI agent that orchestrates your project. It proposes crew compositions, decomposes backlog items into tasks, dispatches tasks to specialists, and synthesizes results.

What are Specialist Agents?

Specialist Agents are AI agents with specific roles like Developer, Designer, QA Engineer, etc. They execute tasks assigned by the PM Agent and communicate results back through the PM.

Can I customize agent behavior?

Yes! You can customize agent system prompts, define custom roles, and configure capability sets to control what tools each agent can access.

How does the PM Agent make decisions?

The PM Agent uses the Claude Code CLI to analyze your project context, documents, backlog items, and sprint goals. It follows a structured decision-making process and maintains a decisions.md file for transparency.

Sprints & Tasks

What is a sprint in Codemus?

A sprint is a goal-based iteration (not calendar-based). You define a sprint goal, select backlog items, and the PM Agent creates tasks to achieve that goal.

How do tasks get assigned?

The PM Agent analyzes task requirements and assigns them to appropriate specialist agents based on their capabilities and current workload.

Can I manually assign tasks?

Yes, you can drag and drop tasks to agents in the graph view, or use the task detail view to reassign tasks manually.

What happens when a task fails?

Failed tasks enter a revision loop. The PM Agent reviews the failure, provides feedback to the specialist, and the task is retried. You can see failure chains in the graph visualization.

Graph Visualization

What does the graph show?

The graph visualizes all entities (projects, sprints, tasks, agents, artifacts, documents) and their relationships. It updates in real-time as your project progresses.

Can I filter the graph?

Yes! Use the graph toolbar to filter by type, status, sprint, or role. You can also search for specific nodes.

What is focus mode?

Focus mode shows only a specific node and its connections at a configurable depth. This helps you focus on a particular area of your project.

Troubleshooting

The app won't start

Check that you're running macOS 14.0 or later and have Apple Silicon. Verify that Claude Code CLI is installed and accessible. Check the Console app for error messages.

Agents aren't responding

Verify Claude Code CLI is configured correctly in Settings. Check your internet connection if using cloud-based models. Review the Flight Recorder for error events.

Graph is slow or laggy

Large projects with many nodes can impact performance. Try using filters to reduce visible nodes, or use focus mode to view smaller subgraphs.

Database errors

Use the database maintenance tools in Settings → About → Database Maintenance. You can run integrity checks, optimize, and repair the database.

Error Messages

"Claude CLI not found"

Configure the path to Claude Code CLI in Settings → CLI. Make sure the CLI is installed and the path is correct.

"Project state transition not allowed"

The Agile State Machine enforces strict transitions. Make sure you've completed all required steps (e.g., creating backlog items before starting a sprint).

"Capability not granted"

An agent tried to use a tool it doesn't have permission for. Review the capability set for that role and grant the necessary permissions, or approve the escalation request.

Performance

How can I improve performance?

Use filters in the graph view, enable focus mode for smaller views, close unused projects, and regularly optimize your database through Settings.

Does Codemus use a lot of memory?

Memory usage depends on project size and number of active agents. Large projects with many documents and artifacts will use more memory. 16GB RAM is recommended for complex projects.

Can I export data to reduce database size?

Yes! Use the export feature to archive completed projects. You can also use the backup system to create compressed backups and remove old data.

Still have questions?

If you can't find the answer you're looking for, please: