Orbitmap Logo | Docs

Projects and Workspaces

What is a Project

A project in Orbitmap represents a single codebase or deployable unit:

  • A web application
  • A backend API service
  • A mobile app version
  • A library or SDK
  • A microservice

Each project has its own:

  • Tasks, issues, ideas, and vibes
  • Documents and documentation
  • Agent assignments
  • Agent instructions template (applied to all new tasks)
  • Git repository URL and default branch

Organizing Projects in a Workspace

A workspace is an optional grouping layer for related projects. Use it when you have multiple codebases that belong to the same product or organization.

Example: A workspace called "Orbitmap" might contain:

  • orbitmap-core - the main Laravel application
  • orbitmap-mcp - the MCP proxy server
  • orbitmap-cli - the command-line tool
  • orbitmap-mobile - the mobile app

Workspace benefits:

  • Shared documents - architecture decisions, coding standards, and guidelines available across all projects
  • Cross-project visibility - see the big picture across all your codebases
  • Workspace-level knowledge - documents tagged as workspace knowledge are automatically included when agents start tasks

Working with a Project

From the web UI, select a project to see its dashboard with tasks, issues, documents, and activity. Use the sidebar to navigate between entities.

From your agent, all commands are automatically scoped to the project configured in your MCP connection (the X-OrbitMap-Project header).

Project Context in MCP vs IDE

MCP configuration with project context (Claude Code, CLI):

In .mcp.json or CLI setup, you specify the project slug in the X-OrbitMap-Project header. The agent always knows which project it's working in.

{
  "headers": {
    "Authorization": "Bearer YOUR_API_KEY",
    "X-OrbitMap-Project": "my-saas-app"
  }
}

IDE without project context (some Cursor/Windsurf setups):

Some IDEs don't support custom headers in MCP configuration. In that case, omit the project header - your agent will have access to all projects in your account and must determine the correct project from context.

terminal
~/mobile-app

❯ HAL, what projects do I have?

HAL: Checking your projects...
✓ get_my_projects()

Your projects:
1. orbitmap-core (workspace: Orbitmap)
2. orbitmap-mcp (workspace: Orbitmap)
3. mobile-app (workspace: MyStartup)

Based on this directory (~/mobile-app),
I'll work in the "mobile-app" project.

The agent infers the project from the working directory, git remote URL, or asks you directly. For best results, always configure the project header when possible.

Download as Markdown