viewing-tasks

Waggle — View Server

You manage the local view server that renders task data as interactive HTML pages.

Session Bootstrap

Invoke the bootstrap-session skill to establish the active provider and current user. Skip if active_provider and current_user are already set in this conversation.

Environment Detection

Before starting, detect the runtime environment:

# Check if running in a remote/sandboxed environment where localhost is not accessible from the user's browser
if [ -n "${CLOUD_SHELL:-}" ]; then
  # Use static HTML export mode (see below)
  STATIC_MODE=true
else
  STATIC_MODE=false
fi

If STATIC_MODE=true, skip "Starting the Server" and go directly to Static HTML Export below.

Starting the Server

The view server runs at http://localhost:3456. To start it:

cd "${CLAUDE_SKILL_DIR}/server" && npm ci --silent && npx tsx src/index.ts &

Before starting, check if it's already running:

curl -s http://localhost:3456/api/health 2>/dev/null

If the health check succeeds, the server is already running. Do NOT start a second instance.

Available Views

View	URL	Status
View Selector	http://localhost:3456/	Available
List	http://localhost:3456/list.html	Available
Kanban	http://localhost:3456/kanban.html	Available
Calendar	http://localhost:3456/calendar.html	Available
Gantt	http://localhost:3456/gantt.html	Available

Opening a View

After ensuring the server is running, open the appropriate URL in the user's browser:

# macOS
open http://localhost:3456/kanban.html

# Linux
xdg-open http://localhost:3456/kanban.html

# WSL
wslview http://localhost:3456/kanban.html

Detect the platform and use the appropriate command.

Initializing Data After Start

After starting the server, push current task data so the view is populated. Follow the Pushing Data to View Server section in the active provider's SKILL.md to:

1. Fetch all tasks from the data source
2. Format as { "tasks": [...], "updatedAt": "<ISO timestamp>", "currentTeam": { "id": "<id>", "name": "<name>" } } (include currentTeam if current_team is set from resolving-identity; omit if null)
3. POST to http://localhost:3456/api/data

Custom Views

Users can create custom visualizations using the managing-views skill. Custom views are served at /custom/<slug>.html.

Opening a Custom View

# macOS
open http://localhost:3456/custom/<slug>.html

# Linux
xdg-open http://localhost:3456/custom/<slug>.html

# WSL
wslview http://localhost:3456/custom/<slug>.html

Listing Custom Views

ls ~/.waggle/views/*.html

Static Export for Custom Views

"${CLAUDE_SKILL_DIR}/scripts/generate-static-html.sh" custom:<slug> /tmp/tasks.json > /tmp/<slug>.html

To create, delete, or regenerate custom views, use the managing-views skill.

View Features

All views support:

• Real-time updates: Connected to SSE at /api/events. Changes made via managing-tasks skill are reflected automatically.
• Client-side filtering: Filter by Status, Priority, search text
• Click-to-copy: Click a task to copy its ID for use in Claude Code
• Dark mode: Default dark theme

Static HTML Export

When running in a remote environment (e.g. cloud shell) where localhost is not accessible from the user's browser, generate a standalone HTML file with embedded task data instead of starting the server.

Steps

1. Fetch all tasks from the data source (follow the active provider's SKILL.md)
2. Save the task data as a temporary JSON file:

cat > /tmp/tasks.json << 'TASKEOF'
{ "tasks": [...], "updatedAt": "<ISO timestamp>" }
TASKEOF

3. Generate the standalone HTML:

"${CLAUDE_SKILL_DIR}/scripts/generate-static-html.sh" <view> /tmp/tasks.json > /tmp/<view>.html

Supported views: kanban, list

4. Present the generated HTML file to the user. In environments that support artifacts (e.g. Claude Desktop), output the HTML content directly so it can be rendered in the browser. Otherwise, inform the user of the file path.

5. Clean up temporary files:

rm -f /tmp/tasks.json /tmp/<view>.html

Static Mode Behavior

• All task data is embedded in the HTML — no server or network access required
• SSE indicator shows "Static" instead of "Live"
• Filtering and search work normally (client-side)
• Back links to the view selector are disabled (single-file mode)

Troubleshooting

If views don't update after task changes:

1. Check the server is running: curl http://localhost:3456/api/health
2. Manually push data: use the managing-tasks skill to query tasks and POST to /api/data
3. Check server logs in the terminal where it's running