AgentJobs

Lightweight task management system designed for AI agent workflows.

Features

• Structured Task Data: YAML-based task definitions with rich metadata
• Browser-Based GUI: View and manage tasks via web interface
• REST API: Programmatic access for agents
• Python Client Library: Simple API for agent integration
• Git-Friendly: All tasks stored as version-controlled YAML files
• Migration Tools: Convert existing Markdown tasks to structured format

Installation

pip install agentjobs

Quick Start

# Initialize in your project
cd /path/to/your-project
agentjobs init

# One-command UI access (starts server + opens browser)
agentjobs open

Server Management

AgentJobs provides convenient commands for managing the web server:

# Open UI in browser (auto-starts server if needed)
agentjobs open

# Start server manually
agentjobs serve

# Check server status
agentjobs status

# Stop the server
agentjobs stop

# Restart with new options
agentjobs restart --reload

VS Code Integration

If you're using VS Code/Antigravity, add a keyboard shortcut for quick access:

1. Open Command Palette (Ctrl+Shift+P)
2. Select "Preferences: Open Keyboard Shortcuts (JSON)"
3. Add:

   {
     "key": "ctrl+alt+u",
     "command": "workbench.action.tasks.runTask",
     "args": "AgentJobs: Open UI"
   }

Now press Ctrl+Alt+U to instantly open the AgentJobs UI!

CLI Commands

Task Management

# Initialize project
agentjobs init

# Create a task
agentjobs create --title "My Task" --priority high

# List all tasks
agentjobs list

# Filter tasks
agentjobs list --status ready --priority high

# Show task details
agentjobs show task-001

# Interactive agent workflow
agentjobs work --agent my-agent

# Load sample data
agentjobs load-test-data

Server Commands

# Open UI (auto-starts server)
agentjobs open

# Manual server control
agentjobs serve [--host HOST] [--port PORT] [--reload]
agentjobs status
agentjobs stop
agentjobs restart

# Example: Start on different port with auto-reload
agentjobs serve --port 9000 --reload

Migration

# Migrate Markdown tasks to YAML
agentjobs migrate source_dir target_dir [--dry-run]

Quick Start for AI Agents

AgentJobs provides a Python client for programmatic task management.

Basic Workflow

from agentjobs import TaskClient

client = TaskClient()  # connects to http://localhost:8765

# Get next task
task = client.get_next_task()

# Take ownership
client.mark_in_progress(task.id, agent="my-agent")

# Get instructions
prompt = client.get_starter_prompt(task.id)

# Work on task...
# (your implementation here)

# Complete
client.mark_completed(task.id, agent="my-agent")

Interactive CLI

# Option 1: Provide agent name
agentjobs work --agent=my-agent

# Option 2: Will prompt for agent name
agentjobs work

Full Documentation

• Agent Workflow Guide
• Examples

Agent Integration

from agentjobs import TaskClient

client = TaskClient()

# Get highest priority task
task = client.get_next_task()

# Mark in progress
client.mark_in_progress(task.id, agent="my-agent")

# Get starter prompt
prompt = client.get_starter_prompt(task.id)

# Add progress update
client.add_progress_update(
    task.id,
    summary="Completed Phase 1",
    details="All tests passing"
)

Documentation

• Installation Guide
• Quick Start
• API Reference
• Agent Workflow Guide
• Task Schema
• Migration Guide

Development

AgentJobs uses itself to manage its own development tasks.

The legacy Task 031 umbrella is now archived in favour of phase-specific tasks (task-033 through task-039) that point at the commits which delivered each milestone.

View Development Tasks

# Quick access
agentjobs open

# Or manually start server
agentjobs serve
# Then open http://localhost:8765 to browse tasks

Contributing

1. Check existing tasks: agentjobs list
2. Inspect a candidate task: agentjobs show task-XXX
3. Claim work: agentjobs work --agent your-name
4. Follow linked prompts and update status via CLI or API
5. Submit a PR referencing the task when ready

Task Structure

• tasks/agentjobs/ - Active AgentJobs roadmap (task-031, task-032, task-033…039)
• tasks/test-data/ - Sample tasks used for demos and load-test-data command
• tasks/privateproject/ - Migrated PrivateProject tasks retained for migration tooling tests
• prompts/ - Phase-specific execution instructions
• examples/ - Agent integration samples
• docs/ - Product and API documentation

Workflow Statuses

AgentJobs tracks work through these stages:

• draft – idea captured, needs design and architecture
• ready – designed, approved, ready for execution
• in_progress / waiting_for_human / under_review – active collaboration
• completed / archived – finished or stored for reference

Local Setup

# Clone repository
git clone https://github.com/jeffposey/agentjobs.git
cd agentjobs

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Start development server
poetry run agentjobs serve

License

MIT License - see LICENSE file for details.