324087e6bb
The README still described molecule-cli as a "TUI dashboard" and used the old `molecli` binary name. After M1 (RFC #10), the primary entry point is `molecule connect <workspace-id>` — the out-of-box bridge between an external-runtime workspace and a local agent backend. Rewritten to: - lead with the connect quick-start (token + API URL + invocation) - document the three built-in backends (claude-code, exec, mock) with --backend-opt examples - list the flags external-workspace operators actually need (--mode, --interval-ms, --since-secs, --dry-run) - note the state-file location (cursor resume across restarts) - link RFC #10 for the full design - fix the binary name (`molecule`, not `molecli`) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> |
||
|---|---|---|
| .claude | ||
| .github/workflows | ||
| bin | ||
| cmd/molecule | ||
| internal | ||
| .gitignore | ||
| .goreleaser.yaml | ||
| CLAUDE.md | ||
| go.mod | ||
| go.sum | ||
| known-issues.md | ||
| pr-description-draft-cli-full.md | ||
| README.md | ||
molecule-cli
Command-line companion for Molecule AI. The primary entry point for external-runtime workspaces — bridge a workspace to a local agent backend (Claude Code, an arbitrary shell command, or a mock for CI).
Install
go install github.com/Molecule-AI/molecule-cli/cmd/molecule@latest
Or download a binary from Releases.
Releases ship Linux/macOS/Windows × amd64/arm64 archives plus a sha256
checksums file (see .goreleaser.yaml).
Quick start — connect an external workspace
When you create a workspace with runtime: external, the platform returns
a per-workspace token. Run:
export MOLECULE_API_URL=https://your-tenant.staging.moleculesai.app
export MOLECULE_WORKSPACE_TOKEN=ws_secret_xxx
molecule connect ws_abcdef
connect registers the workspace, starts heartbeating, polls the platform
for inbound A2A messages, and dispatches each message to the selected
backend. Replies are posted back over the platform API.
Backends
--backend selects how A2A messages are handled. Three are built in:
| Name | What it does |
|---|---|
claude-code |
Default. Invokes claude -p <message> for each turn (claude-code SDK). |
exec |
Runs an arbitrary shell command (--backend-opt cmd=...). Stdout = reply. |
mock |
Echo backend for CI / smoke tests. |
Backend options are passed via repeatable --backend-opt KEY=VALUE:
# Claude Code with a 10-minute per-turn timeout
molecule connect ws_abc \
--backend claude-code \
--backend-opt timeout=10m
# Generic shell handler
molecule connect ws_abc \
--backend exec \
--backend-opt cmd='./my-agent.sh' \
--backend-opt timeout=5m
Other useful flags
--mode poll|push delivery mode (default: poll)
--interval-ms 2000 poll cadence
--since-secs 60 initial activity cursor lookback
--token TOKEN override MOLECULE_WORKSPACE_TOKEN
--dry-run build backend + print summary, exit
State (the activity cursor) is persisted to
~/.config/molecule/state/<workspace-id>.json (mode 0600) so a restart
resumes from the last delivered message.
Other subcommands
molecule agent list / inspect agent sessions
molecule config view / set CLI defaults
molecule completion generate shell completions
The full M1 design is in RFC #10.
License
Business Source License 1.1 — © Molecule AI.