Skip to content
LindenegPublic

About

My way of handling multiple remote (or local) agents across multiple projects

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

7 Commits

Folders and files

Repository files navigation

mingo

My way to handle multiple remote (or local) agents across multiple projects and machines, all from my own computer over ssh. The agents run in Claude Code for now. It was made for myself, so many of the choices may not suit you.

Install

You'll need tmux, git, Go 1.27 or newer, gh and an agent CLI for the sessions, which for now is claude code, the one mingo has a provider for.

git clone https://github.com/Lindeneg/mingo.git
cd mingo && go build -o ~/.local/bin/mingo ./cmd/mingo
mingo install

Make sure ~/.local/bin is on your PATH.

$ mingo help
mingo runs agent sessions for every project on this machine and on the hosts it drives over ssh,
one tmux session per role, each running the project's agent CLI, which for now is Claude Code.

A target is <project>/<role>. A role may be an alias and a project its id, and the project may be
left out inside a project's clone, with MINGO_PROJECT set, or with a default project.

Sessions
  mingo agents [project...]             live sessions with state, uptime and remote link
  mingo attach <target>                 attach, detach with Ctrl+B then D
  mingo away <project>                  the owner is away, the sessions take defaults instead of asking
  mingo back <project>                  the owner is back, the sessions ask again
  mingo clear                           from inside a session, end it so the loop starts a fresh one
  mingo peek <target> [lines]           the last lines of a session's screen
  mingo restart [--force] <target>      end a session where it stands, the loop starts a fresh one
  mingo ro <target>                     attach read only
  mingo say <target> <message>          type a message into a session
  mingo start [--autostart] [target...] start roles, a whole project when no role is named
  mingo status [project...]             each role's state, model and effort, and the agent CLI's login
  mingo stop [target...]                ask sessions to exit, close what is left after a minute and a half

Projects
  mingo default [project]               show or set the default project
  mingo ls                              projects, roles and clones
  mingo memory <target>                 a role's handoff memory
  mingo path <target>                   a role's clone
  mingo project add|show|edit <name>    a project's config in ~/.config/mingo/projects
  mingo repo [project]                  a project's GitHub repository
  mingo service enable|disable <project> start a project's autostart roles at boot, at login on a Mac
  mingo setup <project>                 clone missing roles and make their memory folders

Hosts
  mingo host add <name> <destination>   add a machine reached over ssh, and install this mingo there
  mingo host add <name> --local         add this machine itself
  mingo host ls                         the hosts with where they are and their mingo
  mingo host rm <name>                  take a host off the list

Kit
  mingo apply <project>                 land the files of the project's modules through a pull request
  mingo doctor <project>                what of the project's modules is in place and what is missing
  mingo instructions edit <project>     a local project's instructions file, which mingo apply writes into every clone
  mingo new <name> [--preset p] [...]   a project from a preset, its config, clones and files, asking what flags leave out
  mingo secret review <project>         set the review's token from what the provider's token command printed

Team
  mingo gate <log>                      run the project's gate targets into a log, stopping at the first red one
  mingo heavy <label> -- <command...>   run a heavy command in one of the machine's memory slots
  mingo pr merge <number>               check a ready pull request, then squash merge it
  mingo pr rebase <branch>              rebase a branch onto the base in a worktree, keeping both sides of the shared lists

Other
  mingo help [command]                  this list, or what a command does
  mingo install                         the command, tmux and the agent CLI's settings
  mingo version                         this mingo's version

mingo help <command> explains a command, and so does mingo <command> --help.

Config

A project is one TOML file in ~/.config/mingo/projects.

repo = "you/{project}"
clone = "~/dev/{project}/{role}"
autostart = ["lead"]

[[roles]]
name = "lead"
model = "claude-opus-5-5"
effort = "xhigh"

[[roles]]
name = "dev"
aliases = ["d"]
model = "claude-sonnet-5-5"

Hosts

mingo can run on your own computer and drive the sessions of other machines over ssh. Add each one with mingo host add server you@server, which builds your mingo's exact version there with go install, so the server needs Go, tmux and the agent CLI, and ssh must reach it with a key. Add your computer itself with mingo host add mac --local when it runs sessions too. Hosts are Linux or macOS.

From then on a command goes to the host that has the project: mingo attach shop/lead attaches to the server's session and mingo say shop/dev "pull master" types there. ls, agents and status ask every host and put the host first on each line, and mingo new and mingo project add take --host. A project's config, clones and sessions live on its host, and your computer keeps only ~/.config/mingo/hosts.toml. Each call carries your mingo's version, and a host on another one gets yours installed first, so build mingo from a commit you have pushed.

The kit

The kit is a set of modules. mingo new picks them by preset, and mingo apply lands their files through a pull request.

Preset What's in it
bare sessions and guards
solo bare with one role, plus workflow, ci and review
team solo with any roles, plus skills, team, tracker, rules, and heavy for Node
full everything, heavy only for Node

At a terminal mingo new asks for what its flags leave out, checks each answer as it is given, and says what it will do before it writes anything. Without a terminal the flags and the defaults are all it has.

Module Gives you
sessions the roles, clones, loop and handoffs
guards the write and kill guards
workflow issue, branch, pull request, merge with mingo pr merge, and the skills that go with it
ci a GitHub Actions workflow with a job per check, for pnpm, npm, go or any other stack with its own commands
review an AI review of every pull request, Claude Code's on a project that runs it
skills sub-agents, edge-cases and spend skills
team TEAM.md with the team's rules, and the clear-context skill
tracker planning with Linear or GitHub Issues, and a label per role
rules a ruleset on the base branch
heavy tools/heavy.mjs, which puts a Node project's heavy scripts behind the slots
ports a port offset per role in each clone's .env

The guards catch mistakes, not a session that means to get round them.

On a repository an organization owns, the secret scan of the ci module needs gitleaks' license key, free from gitleaks.io, as the repository's secret GITLEAKS_LICENSE.

A new server

The provision folder turns a fresh Ubuntu server into a mingo machine: a user for the sessions, SSH by key only, a firewall, Docker, Node, Go, gh, tmux and Claude Code.

Make the cloud-init file on your own computer and paste it in as user data when you create the server:

MINGO_USER=you provision/make-cloud-init.sh ~/.ssh/id_ed25519.pub > cloud-init.yaml

The server sets itself up on the first boot and reboots. Then SSH in as that user, run gh auth login and claude auth login, and set your git name and email. Then either install mingo on it as above, or add it from your own computer with mingo host add, which installs mingo there itself.

Every key

id = "sh"                          # a short name that works anywhere the project's name does
title = "Shop"                     # the project's display name, its name by default
repo = "you/{project}"             # owner/name on GitHub
clone = "~/dev/{project}/{role}"   # leave {role} out for a project of one role
lead = "lead"                      # the first role by default
opener = "You are the {role}. Read your handoff memory, then continue."
autostart = ["lead"]               # what mingo service starts at boot
provider = "claude"                # the agent CLI the sessions run, claude (Claude Code) by default and for now the only one
args = ["--permission-mode", "auto", "--remote-control"]   # passed to the CLI, the provider's own by default
agent_files = "repo"               # or local: the instructions file (CLAUDE.md), what it imports and the CLI's folder (.claude) in each clone, out of git
modules = ["workflow", "ci", "review", "team", "tracker"]   # sessions is always on

[[roles]]
name = "lead"
aliases = ["l"]
model = "claude-opus-5-5"
effort = "xhigh"
does = "merges and hands out the work"

[[roles]]
name = "dev"
model = "claude-sonnet-5-5"
effort = "high"
does = "codes the issues labelled dev"

[tracker]
kind = "linear"                    # linear, github or none, none by default, with which the tracker module does nothing
team = "ENG"                       # the Linear team's identifier, which you set when you make the team, and the Closes line then names ENG-n
project = "Shop"

[workflow]
base = "master"
ci = "ci"                          # the workflow whose jobs are the checks
checks = ["check", "test", "build", "security"]   # the checks by the names GitHub shows on a pull request, job ids with the ci module, which needs one
gate = ["pnpm check", "pnpm test", "pnpm build"]  # run without a shell, so no &&, pipes, redirects or quotes
tags = ["(lead)", "(dev)"]         # the role tags a description starts with
reviewer = "claude[bot]"           # whose review comments count, anyone's by default
local_runs = ["pnpm check", "mingo gate"]
# generate_list names the generated files and generate writes them again, for mingo pr rebase. They
# run in a fresh checkout without the clone's installed dependencies, so they must run without them
generate_list = ["node tools/generate.mjs --list"]   # these two without a shell too
generate = ["node tools/generate.mjs"]
generated = '^generate: wrote (.+)$'
# review_line, no_findings, review_heading, footers and trailers tell the review comment and
# attribution apart, and default to "review:", "no findings", "## Review" and the provider's footers
# and trailers, for Claude Code its footer and session link, and Co-Authored-By and Claude-Session

[[workflow.shared]]                # a list everyone appends to
name = "the route list"
pattern = '^src/routes\.ts$'
merge = "lines"                    # lines, json-keys or none

[ci]
stack = "pnpm"                     # pnpm, npm, go or other, which the ci module needs
# setup = ["make deps"]            # other only: the commands CI runs before each check
# audit = "make audit"             # other only: the dependency audit of the security job
[ci.run]
check = "pnpm check"               # a shell line for one of the checks, pnpm <check> or npm run <check> by default

[review]
read = "CLAUDE.md first"           # the instructions file first by default, README.md first when agent_files is local
categories = ["correctness (a wrong result, a crash)", "a missing test for an edge case"]
skip = "formatting, lint or style"

[heavy]
scripts = ["check", "test", "build", "dev"]   # each moves to <script>:run behind the shim

[ports]
variable = "APP_PORT_OFFSET"       # the empty line in .env.example that gets the offset
[ports.offsets]                    # which the ports module needs
lead = 10
dev = 20

[blocks.".claude/skills/task-flow/SKILL.md"]
checks = '''
Run `pnpm check` and the tests of each package the change touches.'''

mingo checks the config each time it reads it, and refuses a key it does not know, a key set to nothing, and a value it cannot use, naming the file, the key and the value. Two projects whose roles would share a tmux session, such as shop's role dev-api and shop-dev's role api, are refused too. While a config does not load, its running loops go on with the config they loaded, and stop, restart, attach, ro, peek and say still reach a session written as <project>/<role>. stop <project> then stops each role that has run a session on this machine.

MINGO_MODEL_<PROJECT>_<ROLE> and MINGO_EFFORT_<PROJECT>_<ROLE> override a role's model or effort for the sessions a start launches.

License

MIT, see LICENSE.

About

My way of handling multiple remote (or local) agents across multiple projects

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages