How to work

Patterns that work well when you run several agents at once. They apply whether you drive BeSwarm by hand or hand the CLI to an orchestrating agent.

General habits

  • Pick a matching skill with beswarm skill list and pass it with --skill <dir>, or use --auto-skills when unsure.
  • Have every agent write its final report to artifacts/ or reports/ so it shows up in the Artifacts panel.
  • Name every agent, and group related agents (--group <name>) so you can wait on and close them together.

Coding

  • One worktree per feature, named after it: worktree add --name <feature> --workspace <ws>. Start the feature's agent in the terminal that add opens.
  • One editing agent per worktree. If a feature needs parallel editors, give each its own worktree.
  • Split by module or layer, not by step — one agent per independent change.
  • Put success criteria in the prompt: which tests, build or lint must pass, and that the agent must run them before finishing.
  • Keep a separate reviewer agent. When the builders finish, prompt it to review each worktree's diff and report only actionable findings.
  • Track features with worktree list, park one with worktree close, and worktree remove it only once it's merged.

Security work

  • Confirm the work is authorized and in scope — your own code, a pentest engagement, a CTF or defensive analysis — and state the scope in every prompt.
  • Keep audits read-only: no file changes, no exploits against live systems, no hosts outside the scope.
  • Analyze untrusted code statically in a dedicated worktree or workspace; don't execute, install or build it.
  • Split by concern — supply chain, auth, injection, secrets — with one named agent each, then have one agent merge and de-duplicate findings.
  • Require findings with file:line, severity, impact and a fix.
  • Treat every permission prompt during security work as your decision; never auto-answer it.

Research and documentation

  • Give each agent one bounded question and a required output format: sources with URLs, key findings, open questions.
  • Ask agents to cite sources and flag anything they couldn't verify.
  • Have one agent merge the individual reports into a single artifact.

Debugging

  • Start one agent to reproduce the problem and write the reproduction steps to an artifact before starting any fix agents.
  • Keep investigation agents read-only; only the agent assigned the fix edits code, in its own worktree.

Work from your phone

BeSwarm's release binaries don't run on Android/Termux, but you don't need them to. Because every tab is a detached helper process, a session keeps running on your Mac or Linux machine while you're away.

  1. Install an SSH client on your phone.
  2. SSH into the macOS or Linux machine where BeSwarm runs.
  3. Run beswarm (or beswarm session attach --name <name>) to reattach to the session, with every agent still where you left it.

If a BeSwarm TUI is still open on that session on the machine, you can skip the TUI on your phone and check in from the shell instead. These commands talk to the running TUI, so with none open they fail with "no beswarm is running":

beswarm agent list
beswarm agent read --name api --source recent-unwrapped --lines 40