README
¶
agentfleet
Run your AI agent fleet from a single terminal dashboard
agentfleet is a Go library for running multiple interactive CLI sessions (Claude Code, Codex, or any command) in parallel with a unified Bubbletea TUI dashboard. Each agent runs independently in a PTY with optional step injection, session recording, and remote attach capabilities via Unix sockets.
Install
Use as a library:
import agentfleet "github.com/hoaitan/agentfleet"
Or try an example directly from source:
git clone https://github.com/hoaitan/agentfleet
cd agentfleet/examples/file-manager
go run . --source tasks.md
Library Quick Start
package main
import (
"context"
"os/signal"
"syscall"
agentfleet "github.com/hoaitan/agentfleet"
"github.com/hoaitan/agentfleet/tui"
)
func main() {
cfg := agentfleet.DefaultConfig()
cfg.Agent = agentfleet.AgentConfigFromTerminal()
ctx, stop := signal.NotifyContext(context.Background(), syscall.SIGINT, syscall.SIGTERM)
defer stop()
fleet := agentfleet.NewFleet(cfg.Fleet)
// Implement Manager to drive tasks into the Fleet:
// mgr := &MyManager{...}
// go mgr.Run(ctx, fleet)
tui.Run(ctx, fleet, cfg.TUI, nil)
}
Examples
| Example | Purpose |
|---|---|
| http-manager | Load tasks from an HTTP endpoint and run agents |
| file-manager | Load tasks from JSON, YAML, or Markdown and run agents |
| generate-manager | Generate tasks via Claude API and run agents |
Fleet Dashboard
┌─────────────────────────────────────────────────────────────────┐
│ agentfleet — 4 agents running │
├─────────────────────────────────────────────────────────────────┤
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ task-1: Running │ │ task-2: Running │ │
│ │ claude │ │ claude │ │
│ │ │ │ │ │
│ │ $ What is today │ │ $ Tell me a joke │ │
│ │ > December 19... │ │ > Why did the... │ │
│ └──────────────────┘ └──────────────────┘ │
│ ┌──────────────────┐ ┌──────────────────┐ │
│ │ task-3: Done │ │ task-4: Failed │ │
│ │ codex │ │ vim │ │
│ │ │ │ │ │
│ └──────────────────┘ └──────────────────┘ │
├─────────────────────────────────────────────────────────────────┤
│ (j/k) scroll | (↵) attach | (q) quit │
└─────────────────────────────────────────────────────────────────┘
Key Bindings
| Key | Action |
|---|---|
j / k |
Navigate between agents (scroll down/up) |
↵ Enter |
Attach to selected agent's terminal |
q |
Quit (stops all running agents) |
Extending
Custom Manager
Implement Manager to control how tasks are loaded and when they run:
package mymgr
import (
"context"
agentfleet "github.com/hoaitan/agentfleet"
)
type GRPCManager struct{ client pb.TaskClient }
func (m *GRPCManager) Run(ctx context.Context, fleet *agentfleet.Fleet) error {
stream, _ := m.client.TaskStream(ctx)
for {
task, err := stream.Recv()
if err != nil { return err }
ag := agentfleet.NewPtyAgent(agentfleet.CommandFields(task))
r := agentfleet.NewRunner(task, ag, agentfleet.DefaultConfig().Fleet)
fleet.Add(ctx, r)
r.Start()
go func(r *agentfleet.Runner) {
<-r.Done()
stream.Send(&pb.Result{Id: r.Task().ID(), Status: r.Status().String()})
}(r)
}
}
Custom Hook
package myhooks
import "github.com/hoaitan/agentfleet/hook"
type MyHook struct{}
func (h *MyHook) Process(data []byte, dir hook.Dir) ([]byte, error) {
if dir == hook.DirOut {
// Transform agent output: redact secrets, annotate, etc.
}
return data, nil
}
Custom Task
package mytasks
import agentfleet "github.com/hoaitan/agentfleet"
type MyTask struct {
agentfleet.BasicTask
CustomField string
}
Custom Source
package mysource
import (
agentfleet "github.com/hoaitan/agentfleet"
"github.com/hoaitan/agentfleet/source"
)
type DatabaseSource struct{ URL string }
func (s *DatabaseSource) Load() ([]agentfleet.Task, error) {
// Query database, return []agentfleet.Task
}
Architecture
| Package | Responsibility |
|---|---|
github.com/hoaitan/agentfleet |
Core: Task, Fleet, Runner, Manager, Agent, Config |
agentfleet/tui |
Bubbletea TUI dashboard — tui.Run(ctx, fleet, cfg, onAttach) |
agentfleet/source |
Task loaders: FileSource, MarkdownSource, HTTPSource, GenerateSource, StepTask |
agentfleet/hook |
Byte processing: Hook, Chain, FileLogger, Logger |
examples/http-manager |
Example: load tasks from HTTP endpoint; includes taskserver/ sub-directory |
examples/file-manager |
Example: load tasks from JSON/YAML/Markdown |
examples/generate-manager |
Example: generate tasks with Claude API |
License
MIT
Documentation
¶
Index ¶
- func CommandFields(t Task) []string
- type Agent
- type AgentConfig
- type BasicTask
- type Config
- type Fleet
- type FleetConfig
- type LogBuffer
- type Manager
- type MockAgent
- func (m *MockAgent) Done() <-chan struct{}
- func (m *MockAgent) Read(p []byte) (int, error)
- func (m *MockAgent) ReadInput(timeout time.Duration) ([]byte, error)
- func (m *MockAgent) Resize(rows, cols int) error
- func (m *MockAgent) SimulateOutput(data []byte) error
- func (m *MockAgent) Start(rows, cols int) error
- func (m *MockAgent) Stop() error
- func (m *MockAgent) Write(p []byte) (int, error)
- type PtyAgent
- type Runner
- func (r *Runner) Done() <-chan struct{}
- func (r *Runner) FinishedAt() time.Time
- func (r *Runner) Lines() []string
- func (r *Runner) Resize(rows, cols int) error
- func (r *Runner) SetOutput(w io.Writer)
- func (r *Runner) Start()
- func (r *Runner) StartedAt() time.Time
- func (r *Runner) Status() Status
- func (r *Runner) StdinWriter() io.Writer
- func (r *Runner) Stop() error
- func (r *Runner) Task() Task
- type Status
- type TUIConfig
- type Task
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CommandFields ¶
CommandFields splits Task.Command() into argv for NewPtyAgent.
Types ¶
type Agent ¶
type Agent interface {
Start(rows, cols int) error
Write(p []byte) (int, error)
Read(p []byte) (int, error)
Resize(rows, cols int) error
Stop() error
Done() <-chan struct{}
}
Agent is any interactive CLI process running in a PTY.
type AgentConfig ¶
type AgentConfig struct {
PTYRows int // default: 24
PTYCols int // default: 220
Env []string // extra env vars (KEY=VALUE); appended to os.Environ() for child process only
}
AgentConfig controls PTY dimensions and environment.
func AgentConfigFromTerminal ¶
func AgentConfigFromTerminal() AgentConfig
AgentConfigFromTerminal reads actual terminal dimensions. Falls back to DefaultConfig().Agent when stdout is not a TTY.
type BasicTask ¶
type BasicTask struct {
TaskID string `json:"id" yaml:"id"`
TaskName string `json:"name" yaml:"name"`
Cmd string `json:"command" yaml:"command"`
}
BasicTask is the default Task implementation.
type Config ¶
type Config struct {
Fleet FleetConfig
TUI TUIConfig
Agent AgentConfig
}
Config holds all configuration for a fleet run.
func DefaultConfig ¶
func DefaultConfig() Config
DefaultConfig returns sensible production defaults.
type Fleet ¶
type Fleet struct {
// contains filtered or unexported fields
}
Fleet is a thread-safe, dynamic registry of Runners. Managers add Runners via Add(); the TUI reads via Runners(). Fleet enforces MaxConcurrent: Add() blocks until a slot is available.
func NewFleet ¶
func NewFleet(cfg FleetConfig) *Fleet
func (*Fleet) Add ¶
Add registers a Runner with the Fleet and blocks until a concurrency slot is available. Returns ctx.Err() if the context is cancelled while waiting. The Runner must already be Start()-ed before calling Add().
type FleetConfig ¶
type FleetConfig struct {
MaxConcurrent int // max tasks running in parallel — default: 9
RingBufferSize int // output lines kept per runner — default: 200
SocketDir string // Unix socket dir; empty = no socket server — default: /tmp
LogDir string // session log dir; empty = no log file — default: /tmp
}
FleetConfig controls task scheduling and I/O paths.
type LogBuffer ¶ added in v0.6.0
type LogBuffer struct {
// contains filtered or unexported fields
}
LogBuffer is a thread-safe line-oriented ring buffer that implements io.Writer. Pass it to slog.NewTextHandler to capture log output; read Lines() in the TUI.
func NewLogBuffer ¶ added in v0.6.0
NewLogBuffer returns a LogBuffer keeping at most maxLines lines.
type Manager ¶
Manager is the orchestration strategy extension point. Implementations load or stream tasks into a Fleet via Add().
type MockAgent ¶
type MockAgent struct {
// contains filtered or unexported fields
}
MockAgent is an in-memory Agent for tests.
func NewMockAgent ¶
func NewMockAgent() *MockAgent
func (*MockAgent) ReadInput ¶
ReadInput reads bytes that were written via Write, blocking up to timeout.
func (*MockAgent) SimulateOutput ¶
SimulateOutput writes bytes as if the agent process produced them.
type PtyAgent ¶
type PtyAgent struct {
// contains filtered or unexported fields
}
PtyAgent runs any CLI process inside a PTY.
func NewPtyAgent ¶
func NewPtyAgent(command []string, cfg AgentConfig) *PtyAgent
type Runner ¶
type Runner struct {
// contains filtered or unexported fields
}
Runner manages one CLI agent session: starts the PTY, proxies I/O, serves a Unix socket for attach, and maintains an output ring buffer. Step injection is not the Runner's concern — callers write to StdinWriter().
func NewRunner ¶
func NewRunner(task Task, ag Agent, cfg FleetConfig, agentCfg AgentConfig) *Runner
func (*Runner) FinishedAt ¶
func (*Runner) Lines ¶
Lines returns all committed lines plus the current partial line being accumulated (bytes received since the last \n). Including the partial line means streaming content is visible in the preview before the agent emits \n.
func (*Runner) Start ¶
func (r *Runner) Start()
Start launches the PTY session, socket server, and log file. Non-blocking. Safe to call multiple times; only the first call has any effect.
func (*Runner) StdinWriter ¶
StdinWriter returns a writer whose bytes are forwarded to the agent's stdin.
type TUIConfig ¶
type TUIConfig struct {
Title func() string // left side of header; nil = "◈ agentfleet"
TitleRight func() string // right side of header, right-aligned (e.g. connection status)
RefreshRate time.Duration // TUI tick interval — default: 500ms
AutoOpen bool // auto-open a tab for each task when it starts — default: true
MaxDoneTasks int // done/failed tasks kept in list; 0 = no limit — default: 10
Log *LogBuffer // nil = no log panel
OnClose func(taskID string) // called when user presses x on a selected task; nil = no-op
FilterLines func([]string) []string // pre-process runner output before preview; nil = default chrome filter
}
TUIConfig controls the Bubbletea dashboard appearance.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
examples
|
|
|
file-manager
command
file-manager demonstrates loading tasks from a JSON/YAML/Markdown file and running them with the agentfleet TUI and step injection.
|
file-manager demonstrates loading tasks from a JSON/YAML/Markdown file and running them with the agentfleet TUI and step injection. |
|
generate-manager
command
generate-manager calls the Claude API to generate tasks from a natural-language goal, shows the generated tasks for confirmation, then runs them with the TUI.
|
generate-manager calls the Claude API to generate tasks from a natural-language goal, shows the generated tasks for confirmation, then runs them with the TUI. |
|
http-manager
command
http-manager demonstrates loading tasks from an HTTP endpoint.
|
http-manager demonstrates loading tasks from an HTTP endpoint. |
|
http-manager/taskserver
command
taskserver is an example HTTP server that serves task definitions to agentfleet.
|
taskserver is an example HTTP server that serves task definitions to agentfleet. |
|
internal
|
|