convez.ai
AgenteAutomaçãoAvançado
Shi-Dong

Ilan CLI - Gerenciador de Agents Claude Code

Shi-Dong/ilan-tools

CLI para orquestrar swarms de Claude Code agents em paralelo

Ver no GitHub
InicialPluginScore · de 0 a 100

Ferramenta de linha de comando para gerenciar e executar um swarm de agents Claude Code em tarefas paralelas. Automatiza a distribuição de tarefas entre múltiplos agents, com suporte a sessões tmux, execução em background e gerenciamento remoto via API.

Instalação

$npx convez-ai Shi-Dong/ilan-tools

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
4
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 4 dias
Versão
—
Issues abertas
0
Contribuidores
2

Casos de uso

  • Executar múltiplas tarefas de código em paralelo com agents Claude
  • Gerenciar fluxo de trabalho de refatoração e bug fixes distribuído
  • Coordenar agents remotamente em servidor centralizado

Veredito

Solução sólida para quem precisa orquestrar múltiplos Claude Code agents em paralelo. Requer Python 3.11+, uv e tmux, e tem curva de aprendizado moderada, mas oferece automação poderosa para workflows de desenvolvimento em larga escala.

README

A tradução para o português deste README ainda está na fila.

Ilan CLI

A CLI tool that manages and runs a swarm of Claude Code agents on a list of user-defined tasks. Each task is dispatched to claude -p in the background; when an agent finishes or gets blocked, the next unclaimed task is picked up automatically.

Installation

Requires Python 3.11+, uv, and tmux.

Each agent's terminal work runs inside tmux sessions prefixed with a unique task hash, so that sessions can be tracked and automatically cleaned up when a task is completed, discarded, or killed.

git clone git@github.com:Shi-Dong/ilan-tools.git
cd ilan-tools
uv venv && uv pip install -e .

The ilan binary is now at .venv/bin/ilan. Add it to your PATH or invoke it directly.

Shell completion

ilan --install-completion zsh   # or bash / fish

Once installed, Tab completes task names, config keys, sub-commands, and options.

Quick start

# Add a task (inline)
ilan add -n fix-bug -d "Fix the null-pointer crash in auth.py"

# Add a task (from file)
ilan add -n big-refactor -f tasks/refactor.md

# See what's running
ilan ls

# Read the latest agent output
ilan tail fix-bug

# Reply to a blocked agent
ilan reply fix-bug "Use the OAuth2 flow instead"
# or even shorter:
ilan re fix-bug "Use the OAuth2 flow instead"

# Omit the message to see the tail first
ilan re fix-bug

# Mark a task as done
ilan done fix-bug

A background server starts automatically on the first command (port 4526). It polls every ~3 seconds, reaping finished agents and spawning new ones up to the concurrency cap.

Warning: --dangerously-skip-permissions is always on. Use at your own discretion.

Remote usage

To manage tasks on a centralized host from another machine, set ILAN_SERVER_URL on the client machine:

export ILAN_SERVER_URL=http://my-server:4526
ilan task ls          # queries the remote server
ilan task add -n fix-bug -d "Fix the crash"   # task runs on the remote host

When the env var is unset, ilan starts and talks to a local server as usual.

When connecting to a remote server, the CLI automatically checks whether the local and server ilan code are built from the same git commit. If they differ, a warning is printed with both commit hashes so you can decide whether to update.

Task aliases

Every non-terminal task is automatically assigned a two-letter alias (e.g. aa, sd, kl) drawn from the characters asdfghjkl. Aliases are displayed in bold magenta in ilan ls and can be used in place of the full task name in any command:

ilan tail sd          # instead of: ilan tail fix-bug
ilan re sd "try v2"   # instead of: ilan re fix-bug "try v2"
ilan done sd

Aliases are assigned when a task is created and released when it transitions to DONE or DISCARDED. If a task is moved back out of a terminal state (via undone / undiscard), it receives a new alias. The alias pool supports up to 81 concurrent non-terminal tasks. To pick a specific alias for an active task, use ilan task alias NAME NEW_ALIAS (or the ilan alias shorthand); the new alias must be two letters from asdfghjkl and not already taken by another task.

Task names must be at least 3 characters long (to avoid ambiguity with aliases) and may only contain letters, digits, hyphens (-), and underscores (_). Aliases are not included in shell tab-completion.

Commands

Tasks

CommandDescription
ilan task add -n NAME -d "prompt"Add a task (or use -f file; name must be ≥ 3 chars, letters/digits/-/_ only)
ilan task ls [-a] [NAME]List active tasks (-a includes DONE/DISCARDED); if NAME is given, show its tail instead
ilan task show NAMEPrint the full prompt of a task
ilan task path NAMEPrint the Claude Code session log path for a task
ilan task tail NAMEShow the last assistant message together with the user prompt that elicited it and any user replies after it
ilan task reply NAME ["msg"]Send a reply to an agent (omit message to show tail)
ilan task tap NAMEAsk for a status update (nudges WORKING agents; re-prompts AGENT_FINISHED/NEEDS_ATTENTION/ERROR tasks)
ilan task sleep NAME DURATIONRe-prompt a NEEDS_ATTENTION / AGENT_FINISHED task to sleep for DURATION and report back. DURATION is an integer or decimal with an optional unit suffix — no whitespace — e.g. 300, 300s, 5m, 2h, 1.5h. Units: s/sec/second/seconds, m/min/mins/minute/minutes, h/hr/hrs/hour/hours; bare numbers are seconds. The task transitions to UNCLAIMED and shows (sleeping for Xs) in ilan ls / ilan dashboard while UNCLAIMED / WORKING.
ilan task log [-p] NAMEOpen the full conversation log in your editor (-p prints the log file path instead)
ilan task summarize NAMESummarize the task's log and print the summary (works on local and remote clients)
ilan task rename OLD NEWRename a task
ilan task alias NAME NEW_ALIASChange the two-letter alias of an active task (NEW_ALIAS must be two letters from asdfghjkl and not already in use)
ilan task branch OLD -n NEW [-d "msg" | -f FILE]Branch a new task from OLD, inheriting its full Claude Code context (both tasks stay repliable and diverge from there)
ilan task kill NAMEKill a WORKING agent, move task to ERROR
ilan task attach NAMEAttach to a task's Claude Code session interactively
ilan task done NAME [NAME...]Mark task(s) as DONE
ilan task discard NAME [NAME...]Mark task(s) as DISCARDED
ilan task undone NAMEMove a DONE task back to NEEDS_ATTENTION
ilan task undiscard NAMEMove a DISCARDED task back to NEEDS_ATTENTION
ilan task unread NAME [NAME...]Restore the unread marker on task(s)
ilan task max NAMERun this task on the Fable model (claude-fable-5) instead of the default; a red FABLE tag shows in the Cost column in ilan ls / ilan dashboard. Takes effect on the task's next agent spawn.
ilan task unmax NAMEReset the task's model back to the model config default
ilan task rm [-f] NAME [NAME...]Delete task(s) and all their data (refuses if any has an active descendant; -f overrides)

Shorthands

Frequently used task commands have top-level aliases to save typing:

ShorthandEquivalent
ilan addilan task add
ilan ls [-a] [NAME]ilan task ls [-a] [NAME]
ilan tail NAMEilan task tail NAME
ilan reply NAME ["msg"]ilan task reply NAME ["msg"]
ilan re NAME ["msg"]ilan task reply NAME ["msg"]
ilan rename OLD NEWilan task rename OLD NEW
ilan alias NAME NEW_ALIASilan task alias NAME NEW_ALIAS
ilan branch OLD -n NEWilan task branch OLD -n NEW
ilan tap NAMEilan task tap NAME
ilan sleep NAME DURATIONilan task sleep NAME DURATION
ilan attach NAMEilan task attach NAME
ilan log [-p] NAMEilan task log [-p] NAME
ilan summarize NAMEilan task summarize NAME
ilan sum NAMEilan task summarize NAME
ilan done NAME [NAME...]ilan task done NAME [NAME...]
ilan discard NAME [NAME...]ilan task discard NAME [NAME...]
ilan undone NAMEilan task undone NAME
ilan undiscard NAMEilan task undiscard NAME
ilan unread NAME [NAME...]ilan task unread NAME [NAME...]
ilan max NAMEilan task max NAME
ilan unmax NAMEilan task unmax NAME

Dashboard

ilan dashboard

Full-screen, real-time task table (like htop). Polls the server at the configured dashboard-interval (default: every 1 second). Keybindings: q quit, r force-refresh. The "refreshed at" timestamp uses the configured time-zone.

Each row's Status cell carries a Haiku-generated one-line summary of the agent's most recent reply (≤ 20 words). The summary is refreshed only on WORKING → NEEDS_ATTENTION / AGENT_FINISHED transitions and requires the server's api-key to be set. Toggle whether the client renders it with ilan config set one-line-summary true|false (default true); if the toggle is on but the server has no api-key, the client prints a warning above the table. A thin separator is drawn between every task row in both ilan ls and ilan dashboard; branched (child) tasks remain visually nested under their parent via the existing tree-prefix indentation.

Server

CommandDescription
ilan server statusShow whether the background server is running
ilan server restartRestart the server (picks up code changes)
ilan server stopStop the background server
ilan ping [-c N]Measure round-trip latency to the server. With ILAN_SERVER_URL set, sends N health requests (default 3) and prints the rounded average round-trip time in ms. Without it, just notes that the server is local.

Config

CommandDescription
ilan config showPrint current configuration
ilan config set KEY VALUESet a config value
ilan clean DURATIONDelete tasks whose last change is older than DURATION (e.g. 5h, 3d); never touches tasks that have children
ilan clear-everythingDelete all tasks, logs, and data (requires confirmation)
ilan updatePull the latest ilan-tools from remote and reinstall

Configuration keys

Configuration is stored at ~/.config/ilan/config.json (created with defaults on first run).

KeyDefaultDescription
workdir~/.ilanWhere all ilan data is stored
num-agents5Max concurrent Claude Code agents
time-zoneUS/PacificTime zone for displayed timestamps (client-side: set on each machine running the CLI)
modelopusClaude model passed to claude -p
efforthighEffort level for the model
summarize-modelsonnetClaude model used by ilan task summarize
summarize-effortmediumEffort level used by ilan task summarize
editoremacsEditor used by ilan task log
api-key(empty)Anthropic API key passed as ANTHROPIC_API_KEY to spawned agents; also used to call Haiku for the one-line status summary in ilan ls and ilan dashboard
dashboard-interval1Seconds between automatic refreshes in ilan dashboard
line-numberfalseWhen true, ilan tail prefixes each assistant line with a yellow [N] marker and ilan reply / ilan task branch expand @N into the Nth line, double-quoted
one-line-summarytrueClient-side: render the Haiku-generated one-line summary in the Status column of ilan ls and ilan dashboard. The summary is always produced by the server when api-key is set; this flag only controls whether the client shows it. If on while the server has no api-key, the client prints a warning.

Line-number mode

Turn it on with:

ilan config set line-number true

Then ilan tail <task> prints each line of every shown assistant message with a yellow [N] prefix; numbering is continuous across all assistant messages when -n surfaces more than one. ilan reply (and its re shorthand) then looks up the most recent tail for that task and replaces every @N in your reply with the Nth line wrapped in double quotes — so ilan reply my-task "about @12, ..." becomes about "the 12th line ...", ... before being sent. Out-of-range references pass through unchanged.

ilan task branch (and its branch shorthand) does the same expansion on its first reply (-d "..." or -f FILE), looking up the cached tail of the parent task — so you can ilan tail parent and then ilan task branch parent -n child -d "redo @12 differently" and the child task starts with the parent's 12th line already quoted.

You can override the config for a single invocation with the --line-number / --no-line-number flags on ilan tail (and on ilan re / ilan ls when only a task name — no response message — is given):

ilan tail my-task --line-number       # force line numbers on
ilan re my-task --no-line-number      # tail without line numbers

--no-line-number also drops the Rich Panel border around each entry — just a plain Assistant / User header followed by the message body — so you can copy the content straight out of the terminal without sweeping up any box-drawing characters. --line-number keeps the full boxed rendering since the [N] prefixes need a panel-relative width to not wrap.

Passing the flag together with a response message (ilan re my-task "some response" --no-line-number) is rejected, since the flag only affects how tail output is rendered.

line-number is a client-side config: ilan config set line-number true writes to the local ~/.config/ilan/config.json instead of going through the server, so the toggle works the same way whether you're driving a local or remote ilan server (set it on the machine you're running the CLI on).

Summarize

ilan summarize fix-bug   # or: ilan sum fix-bug / ilan task summarize fix-bug

ilan summarize asks the ilan server to feed the task's JSONL log into a fresh claude -p invocation (using summarize-model / summarize-effort) and write a markdown summary next to the log at <workdir>/logs/<task>.summary.md. The summary text is then printed on the command line, so it works the same way from a local shell or from a client machine connected to a remote server via ILAN_SERVER_URL. The summary includes each PR the task produced (link + one-line description) and each wandb run (link + current status). Re-running on an unchanged task skips the claude call and reprints the cached summary.

The prompt template is a plain file at src/ilan/prompts/summarize.md — edit it in place if you want to tweak what the summary looks like.

Fable model (ilan max / ilan unmax)

ilan max my-task      # run my-task on claude-fable-5
ilan unmax my-task    # back to the default model

ilan max pins a single task to Anthropic's Mythos-class Fable model (claude-fable-5), leaving every other task on the configured model default. While a task is maxed, a red FABLE tag is rendered on its own line in the Cost column (beneath the cost) in ilan ls and ilan dashboard. The override is per task and persists across replies until you run ilan unmax, which clears it back to the model config default. A change takes effect on the task's next agent spawn (the next reply / scheduled run), not on an already-running agent.

Task lifecycle

UNCLAIMED ──▶ WORKING ──▶ AGENT_FINISHED ──▶ DONE
                │               │
                │               ▼
                │         NEEDS_ATTENTION ◀── undone
                │               │
                ▼               ▼
              ERROR        (reply) ──▶ UNCLAIMED
                │
                ▼
           (reply) ──▶ UNCLAIMED

                        DISCARDED ◀── discard
                            │
                            ▼
                      (undiscard) ──▶ NEEDS_ATTENTION

Agents self-report their status via a [STATUS: DONE] or [STATUS: NEEDS_ATTENTION] marker injected into every prompt. The injected convention also requires the agent to provide a substantive answer before emitting the marker.

All claude -p processes are spawned with cwd set to the configured workdir so that Claude Code stores sessions under a consistent project directory. This ensures --resume can always locate prior sessions.

Architecture

┌─────────────┐         HTTP/JSON           ┌──────────────────┐
│  ilan CLI   │ ◀─────────────────────────▶ │  ilan server     │
│  (client)   │    localhost:4526           │  (background)    │
└─────────────┘                             │                  │
                                            │  ┌────────────┐  │
                                            │  │ scheduler  │  │ ── poll every 3s
                                            │  └────────────┘  │
                                            │        │         │
                                            │        ▼         │
                                            │  ┌────────────┐  │
                                            │  │ runner     │  │ ── spawns claude -p
                                            │  └────────────┘  │
                                            │        │         │
                                            └────────┼─────────┘
                                                     ▼
                                            ┌────────────────┐
                                            │  ~/.ilan/      │
                                            │  tasks.json    │
                                            │  logs/*.jsonl  │
                                            │  output/*.json │
                                            └────────────────┘

The server auto-starts on the first CLI command and recovers gracefully on restart by reading task state and agent output files from the workdir.

Ver o original no GitHub

Bom para

Relacionados