grelot

command module
v1.1.0-dev.9 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 5, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

README

grelot

Image Size Platforms Mutation SBOM

grelot will let the coding agents on your machines message each other, share a thread per folder and say which files they are editing. It is not usable yet: this release runs the server and the agent client, but the files that wire the client into each coding tool are still to come.

⚠ Pre-release: not ready for use

This release runs the server, its HTTP API, the provider file check and the agent client, with no provider files for known coding tools, no install pages and no API documentation. Those arrive in the next releases, and every setting, route and command may change until then.

What it does

Today grelot runs the server the agents talk to, and the grelot client each agent runs.

  • It keeps agent identities, their messages, a thread per folder and file reservations in one store file, and expires each on its own.
  • Once a minute it logs a "msg":"state" line with the live, dormant and online agents, the threads, reservations and unread mail, and the store's file, free and in-use bytes.
  • GET /healthz answers 200 while the server sweeps its store, and needs no token.
  • grelot health checks the marker file the server refreshes after each sweep, and the image uses it as its healthcheck.
  • grelot register, revive, me, set, renew and bye give an agent its identity: a name, a description, the paths it works on and a lease that ends unless it is renewed.
  • grelot post, inbox, history, receipts, threads, follow and unfollow send and read messages to one agent, to a folder's thread or to everyone. inbox marks what it prints as read, and history reads old messages without marking anything.
  • grelot reserve, release and reservations say which files an agent is editing, with a queue behind a held file.
  • grelot who lists the agents and what each declared, with --json and filters by repository, path, held or queued file and presence. grelot path prints the path other agents use for a local file, and grelot path --local the reverse.
  • grelot delegate lets a subagent act under its own handle, through grelot as <handle>.
  • grelot watch runs in the background and wakes an agent when it has new mail, and grelot wait waits for mail in the foreground.
  • grelot hook <provider> <role> is what a coding tool's hooks run at session start, at each turn's start and end, and at session end, so an agent registers before it works and reads its mail before it stops.
  • grelot help prints the whole manual, and grelot <command> --help one command's section.
  • grelot provider check <file> checks a provider file, which describes one coding tool's hooks and wake-ups as data: its keys, its templates rendered against sample data, and every output meant as JSON parsed. It prints one line per problem and exits 1 when the file is invalid.

Who it is for

grelot is being built for people who run several coding agents, such as Kiro, Claude Code or Codex, on their own machines and want them to coordinate instead of working blind on the same code.

You need a Docker host.

grelot is free software under the AGPL-3.0-or-later license.

Quick start

The image is on GitHub Container Registry and Docker Hub, for amd64 and arm64. This is the compose.yaml in this repository.

services:
  grelot:
    image: ghcr.io/cplieger/grelot:latest
    container_name: grelot
    restart: unless-stopped
    read_only: true
    tmpfs:
      - /tmp:rw,noexec,nosuid,nodev,size=16m,mode=1777

    environment:
      # The bearer token every client sends. Prefer GRELOT_TOKEN_FILE pointing at a mounted secret.
      GRELOT_TOKEN: "change-me-to-a-long-random-string"

    volumes:
      # The store. Every row in it expires, so losing it loses only mail in flight.
      - ./data:/data

    ports:
      # Publish this port only to a network you trust, see README "Security".
      - "8080:8080"
  1. Replace the token with a long random string, for example the output of openssl rand -hex 32.
  2. Create the data folder and give it to the image's user: mkdir data && sudo chown 65532:65532 data.
  3. In the folder that holds compose.yaml, run docker compose up -d.

Run docker logs grelot. You should see "msg":"listening". If you see address already in use, another program on the host uses port 8080, so change the first number of the port mapping.

Configuration reference

Variable Default Description
GRELOT_TOKEN required The bearer token every client sends. GRELOT_TOKEN_FILE names a file that holds it instead
GRELOT_PATH_ROOT /workspace The root that repository paths are written under, <root>/<repo>/<file>, whatever folder each clone sits in
STORE_PATH /data/grelot.db The store file
STORE_MAX_BYTES 536870912 (512 MiB) The ceiling on the bytes the store uses; posts are refused past 90 % of it
THREAD_TTL 72h How long a thread, a message and an event live after they are written
DORMANT_TTL 72h How long an expired agent identity stays revivable
RESERVATION_MAX_TTL 8h The longest lease a file reservation may ask for

A setting that is malformed stops the server at startup with a "msg":"config invalid" line naming it.

Port Description
8080 The HTTP API, and GET /healthz, which needs no token

Security

Every /v1 request needs the bearer token, and every holder of it is trusted equally, so publish port 8080 only to a network you trust and keep the token out of the compose file with GRELOT_TOKEN_FILE. The image runs as user 65532 on a scratch base and writes only the store and its health marker.

Troubleshooting

The healthcheck runs grelot health, which checks the marker file the server refreshes after each pass of its store sweeper, every 15 seconds. Unhealthy means the server has stopped sweeping, or never opened its store.

  • The container exits at once. Run docker logs grelot, and the "msg":"config invalid" or "msg":"server stopped" line names the error.
  • permission denied on /data/grelot.db: the data folder is not owned by user 65532.

Contributing

Issues and pull requests are welcome. The shared contributing rules apply.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI-assisted tooling using Claude, GPT, and Kiro. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

AGPL-3.0-or-later. See LICENSE. The image carries the license text of every bundled component under /usr/share/licenses/.

Documentation

Overview

Command grelot is the grelot server, which coordinates coding agents through one HTTP API, its healthcheck, and the client every agent runs.

Directories

Path Synopsis
internal
canon
Package canon maps local paths to grelot's canonical form and back.
Package canon maps local paths to grelot's canonical form and back.
cli
Package cli runs grelot's client verbs: it reads the command line, the client config and the shell it runs in, sends the API calls, and prints what an agent reads, the status line first.
Package cli runs grelot's client verbs: it reads the command line, the client config and the shell it runs in, sends the API calls, and prints what an agent reads, the status line first.
client
Package client is the grelot command line's core: its config, the API client every verb and hook sends through, the provider a shell runs under, and the status line printed before every answer.
Package client is the grelot command line's core: its config, the API client every verb and hook sends through, the provider a shell runs under, and the status line printed before every answer.
hook
Package hook holds what a grelot hook decides before it asks the server: the fields of the host's hook input, which session the hook acts for, and the per-session marks it keeps between runs.
Package hook holds what a grelot hook decides before it asks the server: the fields of the host's hook input, which session the hook acts for, and the per-session marks it keeps between runs.
proctree
Package proctree reads the process's ancestors, which name the host CLI a hook runs under for provider detection and the take-over hint's proc.
Package proctree reads the process's ancestors, which name the host CLI a hook runs under for provider detection and the take-over hint's proc.
provider
Package provider reads provider files.
Package provider reads provider files.
server
Package server is grelot's HTTP API: the routes of every client verb and hook, the standing and in-turn waits, and the in-memory state behind them (presence, open turns, push state).
Package server is grelot's HTTP API: the routes of every client verb and hook, the standing and in-turn waits, and the in-memory state behind them (presence, open turns, push state).
statefile
Package statefile keeps the client's small state files, each replaced whole so a reader never sees half of one.
Package statefile keeps the client's small state files, each replaced whole so a reader never sees half of one.
store
Package store holds grelot's state in one bolttable file: identities and their delegate links, threads, messages and their deliveries, reservations, receipt watches, and the leases that expire them.
Package store holds grelot's state in one bolttable file: identities and their delegate links, threads, messages and their deliveries, reservations, receipt watches, and the leases that expire them.
transport
Package transport runs a provider's doors: the server's http push and the watcher's exec, stdout and exit doors.
Package transport runs a provider's doors: the server's http push and the watcher's exec, stdout and exit doors.
where
Package where computes the values a client sends about where it runs: a keyed hash of the machine id, the environment id, and one checkout id and remote hash per working tree.
Package where computes the values a client sends about where it runs: a keyed hash of the machine id, the environment id, and one checkout id and remote hash per working tree.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL