taskfloor-agent

Local agent that connects Claude Code to your TaskFloor task board. It runs as a background daemon, auto-discovers your projects by matching git remotes, and executes tasks in isolated git worktrees with real-time streaming to the browser.

Installation

# Recommended (isolated environment)
pipx install taskfloor-agent

# Or with pip
pip install taskfloor-agent

Requires Python 3.10+.

Quick Start

1. Login — configure your server URL and agent token (get the token from TaskFloor Settings):

   taskfloor-agent login
   

2. Start — run the agent in the background:

   taskfloor-agent start
   

3. Check status — verify the agent is connected:

   taskfloor-agent status
   

Commands

How It Works

The agent connects to your TaskFloor server via WebSocket, receives task assignments, and runs Claude Code sessions in isolated git worktrees. Each task gets its own branch (taskfloor/task-{id}) and worktree (.worktrees/task-{id}), so work is isolated from your main branch.

Project discovery is automatic — the agent scans your configured directories for git repos and matches their remotes against TaskFloor projects.

Configuration

Config file: ~/.taskfloor/agent.yaml

server: https://taskfloor.xyz
token: <your-agent-token>
agent_id: username-hostname
scan_dirs:
  - ~/Projects
project_paths:
  - ~/Projects/my-specific-repo

Links

• TaskFloor — task management platform
• Repository
• Issues