Documentation

What is NowBuilding?

NowBuilding is a project management platform designed for building in public. It combines traditional task management with AI-powered ideation and agent integration, making it perfect for indie hackers, solo developers, and teams who want to share their progress transparently.

• Create beautiful public project pages to share your progress
• Organize work using an Azure DevOps-style hierarchy
• Let AI agents work on your tasks automatically
• Use AI to brainstorm and generate project requirements

Creating Your First Project

1. Sign up at nowbuilding.tech/signup
2. Create a project — give it a name and description
3. Make it public (optional) — enable the public page in project settings
4. Add work items — create epics, features, stories, tasks, and bugs
5. Start building! — drag items across the kanban board as you progress

Understanding the Backlog

Your backlog is where all work items live. Items flow through statuses:

Kanban Board

Visualize your work with a drag-and-drop kanban board. Move items between columns as work progresses. Filter by item type, assignee, or search by title.

Backlog Management

Manage your backlog with powerful filtering, sorting, and bulk actions. Prioritize work, set story points, and organize items into a hierarchy.

AI Ideation (PIL Framework)

Use the Productive Insight Loop (PIL) to brainstorm your project with AI. Chat about your idea and the AI will help you:

• Refine your project vision
• Generate a Product Requirements Document (PRD)
• Create user stories and tasks
• Identify potential challenges and solutions

Work Item Types

NowBuilding uses a hierarchy inspired by Azure DevOps:

Public Project Pages

Share your progress with the world! Enable a public page for your project and anyone can see your kanban board, backlog, and progress. Perfect for:

• Building in public and gathering feedback
• Showing potential users what's coming
• Demonstrating your work to employers or clients
• Keeping stakeholders informed without giving access

What is the Agent API?

The Agent API allows AI coding assistants (like Claude, Cursor, GitHub Copilot, etc.) to interact with your project's task list. Agents can:

• Fetch the recommended next task to work on
• Claim tasks and mark them as in-progress
• Update progress with notes
• Complete tasks with summaries
• Mark tasks as blocked when they hit obstacles
• Create new tasks when they discover additional work

Enabling the Agent API

1. Navigate to your project's Settings
2. Click on Agent API in the sidebar
3. Toggle Enable Agent Access
4. Click Generate Key to create an API key
5. Copy and securely store your key (it won't be shown again!)

Security Model

API Endpoints

curl -H "Authorization: Bearer nb_agent_xxxxx" \
  https://nowbuilding.tech/api/agent/next

{
  "task": {
    "id": "abc-123",
    "title": "Implement login form",
    "description": "Create a login form with email/password",
    "type": "task",
    "status": "ready",
    "priority": "high",
    "acceptance_criteria": [...]
  },
  "reasoning": "High priority task with no blockers"
}

curl -H "Authorization: Bearer nb_agent_xxxxx" \
  "https://nowbuilding.tech/api/agent/tasks?status=ready&type=task"

{
  "tasks": [
    { "id": "abc-123", "title": "...", "status": "ready", ... },
    { "id": "def-456", "title": "...", "status": "ready", ... }
  ]
}

curl -X POST -H "Authorization: Bearer nb_agent_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "abc-123", "agent_identifier": "my-agent"}' \
  https://nowbuilding.tech/api/agent/claim

{
  "success": true,
  "task": { "id": "abc-123", "status": "in_progress", ... },
  "message": "Task claimed successfully"
}

curl -X POST -H "Authorization: Bearer nb_agent_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "abc-123", "notes": "Implemented form validation"}' \
  https://nowbuilding.tech/api/agent/update

{
  "success": true,
  "message": "Task updated successfully"
}

curl -X POST -H "Authorization: Bearer nb_agent_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "abc-123", "notes": "Added login form with tests"}' \
  https://nowbuilding.tech/api/agent/complete

{
  "success": true,
  "message": "Task completed successfully"
}

curl -X POST -H "Authorization: Bearer nb_agent_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"task_id": "abc-123", "reason": "Need API credentials", "blocked_type": "access"}' \
  https://nowbuilding.tech/api/agent/block

{
  "success": true,
  "message": "Task marked as blocked"
}

curl -X POST -H "Authorization: Bearer nb_agent_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Add rate limiting", "description": "...", "item_type": "task", "priority": "high"}' \
  https://nowbuilding.tech/api/agent/create

{
  "success": true,
  "task": { "id": "ghi-789", "title": "Add rate limiting", ... },
  "message": "Task created and added to backlog"
}

What is MCP?

The Model Context Protocol (MCP) is a standard for connecting AI assistants to external tools and data sources. NowBuilding provides an MCP server that lets tools like Claude Desktop and Cursor interact with your tasks natively.

Setup Instructions

1. Clone or download the MCP server from your NowBuilding project's tools/mcp-server/ directory
2. Install dependencies: npm install
3. Configure your MCP-compatible tool (see examples below)

Available Tools

Claude Desktop Configuration

Add to ~/.config/claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nowbuilding": {
      "command": "node",
      "args": ["/absolute/path/to/tools/mcp-server/index.js"],
      "env": {
        "NOWBUILDING_API_KEY": "nb_agent_xxxxx"
      }
    }
  }
}

Cursor Configuration

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "nowbuilding": {
      "command": "node",
      "args": ["./tools/mcp-server/index.js"],
      "env": {
        "NOWBUILDING_API_KEY": "nb_agent_xxxxx"
      }
    }
  }
}

Setup

1. Save your API key:

   echo "nb_agent_xxxxx" > ~/.config/nowbuilding_key
   chmod 600 ~/.config/nowbuilding_key

2. Add the CLI to your PATH:

   # Option 1: Symlink
   sudo ln -s /path/to/NowBuilding/tools/cli/nb /usr/local/bin/nb
   
   # Option 2: Add to PATH
   export PATH="/path/to/NowBuilding/tools/cli:$PATH"

Commands Reference

nb list              # All tasks
nb list ready        # Ready tasks only
nb list --type bug   # Bugs only
nb list backlog --type task

nb block abc-123 "Need DB credentials" access
nb block abc-123 "Waiting for design review" decision

nb create "Fix login bug"
nb create "Add caching" "Implement Redis caching for API" task high
nb create "Payment flow broken" "" bug critical

Environment Variables