taskfloor-agent 0.2.0

Local agent for TaskFloor — connects Claude Code to your task board

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

Command	Description
taskfloor-agent login	Configure server URL, token, and scan directories
taskfloor-agent start	Start agent daemon (use --foreground for dev)
taskfloor-agent stop	Stop background daemon
taskfloor-agent status	Show config, connection, and discovered projects
taskfloor-agent logs	View agent logs (-f to follow)
taskfloor-agent add <path>	Add a local project directory
taskfloor-agent cleanup	Remove TaskFloor worktrees from local repos

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