bootspring_dashboard | Bootspring Docs

Get dashboard status, start the dashboard server, or get the URL.

Overview#

The bootspring_dashboard tool manages the Bootspring real-time dashboard. The dashboard provides a visual interface for monitoring project status, viewing todo lists, tracking workflows, and more.

Parameters#

Parameter	Type	Required	Description
`action`	string	No	Action to perform (default: `status`)

Actions#

Action	Description
`status`	Check if dashboard is running
`url`	Get the dashboard URL
`start`	Start the dashboard server
`stop`	Stop the dashboard server

Usage Examples#

Check Status#

Use the bootspring_dashboard tool with:
- action: "status"

Response (running):

{
  "status": "running",
  "port": 3456,
  "url": "http://localhost:3456",
  "command": "bootspring dashboard"
}

Response (stopped):

{
  "status": "stopped",
  "port": 3456,
  "url": "http://localhost:3456",
  "command": "bootspring dashboard"
}

Get URL#

Use the bootspring_dashboard tool with:
- action: "url"

Response:

http://localhost:3456

Start Dashboard#

Use the bootspring_dashboard tool with:
- action: "start"

Response (success):

{
  "status": "started",
  "port": 3456,
  "url": "http://localhost:3456",
  "pid": 12345,
  "message": "Dashboard started successfully"
}

Response (already running):

{
  "status": "already_running",
  "port": 3456,
  "url": "http://localhost:3456",
  "message": "Dashboard is already running"
}

Response (failed):

{
  "status": "failed",
  "port": 3456,
  "url": "http://localhost:3456",
  "pid": null,
  "message": "Failed to start dashboard"
}

Stop Dashboard#

Use the bootspring_dashboard tool with:
- action: "stop"

Response (success):

{
  "status": "stop_requested",
  "message": "Stop signal sent. Dashboard should stop shortly."
}

Response (not running):

{
  "status": "not_running",
  "message": "Dashboard is not running"
}

Configuration#

Configure the dashboard port in bootspring.config.js:

module.exports = {
  dashboard: {
    port: 3456  // Default port
  }
};

Dashboard Features#

The real-time dashboard provides:

Project Overview#

Project health status
Current development phase
Open issues count

Todo Management#

View pending and completed todos
Mark items complete
Add new tasks

Workflow Tracking#

Active workflow progress
Step-by-step guidance
Checkpoint status

Agent Activity#

Recent agent invocations
Suggested agents
Agent response history

Quality Metrics#

Lint status
Test coverage
Type errors

CLI Integration#

The dashboard can also be started via CLI:

# Start dashboard
bootspring dashboard

# Start on custom port
bootspring dashboard --port 4000

Technical Details#

Process Management#

Dashboard runs as a detached process
Survives terminal closure
Uses unref() for independent lifecycle

Port Detection#

Checks if port is already in use
HTTP health check for status detection
1 second timeout for port checks

Startup Sequence#

Check if already running
Spawn Node.js process
Wait 1 second for startup
Verify server is responding

Error Handling#

Port in Use#

If the port is already in use by another application:

{
  "status": "failed",
  "message": "Failed to start dashboard"
}

Solution: Change the port in configuration or stop the conflicting process.

Permission Denied#

If the port requires elevated permissions (ports < 1024):

{
  "status": "failed",
  "message": "Failed to start dashboard"
}

Solution: Use a port above 1024 or run with elevated permissions.

Best Practices#

Keep Dashboard Running#

Start the dashboard at the beginning of your development session for real-time monitoring.

Use Status Checks#

Before starting, check status to avoid duplicate processes.

Configure Port#

If port 3456 conflicts with other services, configure a different port.

bootspring_todo - Manage todos shown in dashboard
bootspring_workflow - Workflows tracked in dashboard
bootspring_quality - Quality metrics in dashboard