galinum-cli

Universal agent inbox. Any product can send messages through the Galinum SDK; any agent can read them through this CLI.

Agents typically have no inbox. They run, they exit, and any message that arrives in between is lost.

galinum gives every agent a durable inbox. Products publish messages through the Galinum SDK, the CLI polls or listens, and the agent reads them on the next turn. Works in any harness — Claude Code, Codex, your own runtime.

Install

curl -fsSL https://galinum.com/install.sh | bash

This downloads the latest Galinum CLI binary from GitHub Releases.

Or install from npm:

npm install -g @galinum/cli

Requires Node.js 20 or later. Written in TypeScript; zero runtime dependencies.

Agent skill

This package includes skills/galinum-cli/SKILL.md so agent harnesses can learn the setup flow, command contract, and secret-handling rules without relying on README parsing.

Quick start

# 1. Create an identity for this agent (stored in ~/.galinum/config.json)
galinum identify --name "my-agent" --harness codex

# 2. Subscribe using an invite code from a product
galinum subscribe inv_xxxxxxxxxxxxxxxx

# 3. Read pending messages
galinum fetch

# Or keep listening
galinum listen

Commands

identify

Create and store this agent's Galinum identity.

galinum identify --name <name> [--harness <value>] [--reset]

| Flag | Meaning | | --- | --- | | --name | Human-readable agent name. | | --harness | The runtime this agent runs in (claude-code, codex, openclaw, hermes, custom, …). | | --reset | Replace an existing stored identity. |

subscribe

Subscribe to a project's inbox using an invite code.

galinum subscribe <invite-code>

Invite codes follow the format inv_<16-128 url-safe chars>.

subscriptions

List local subscriptions.

galinum subscriptions

unsubscribe

Remove a local subscription.

galinum unsubscribe <project-slug>

fetch

Fetch pending messages once. Messages are acknowledged after they are printed.

galinum fetch [project-slug]

listen

Continuously poll for new messages.

galinum listen [project-slug] [--interval-seconds 30]

Ctrl+C stops cleanly.

Global flags

| Flag | Purpose | | --- | --- | | --config <path> | Override config location (default: ~/.galinum/config.json). | | --base-url <url> | Override the Galinum API base URL (useful for staging). |

Configuration

The CLI stores state in ~/.galinum/config.json (file mode 0600, directory mode 0700):

{
  "agent": {
    "id": "agt_…",
    "name": "my-agent",
    "harness": "codex",
    "key": "<bearer key>"
  },
  "subscriptions": [
    {
      "project": "acme",
      "baseUrl": "https://galinum.com",
      "inboxId": "ibx_…",
      "key": "<bearer key>"
    }
  ]
}

The key fields are bearer tokens — treat the file like an SSH key.

Integrating with agent harnesses

galinum fetch exits cleanly when there are no pending messages, so it's safe to call frequently from a session-start or pre-task hook. Example:

# In your agent's startup hook
galinum fetch --quiet || true

Long-running agents can run galinum listen in the background and pipe its output into the conversation.

Contributing

See CONTRIBUTING.md. Bug reports and small PRs welcome.

License

Apache-2.0 © Galinum