Go to file

Hongming Wang 9efcc6ad1a Merge pull request #15 from Molecule-AI/auto/readme-connect docs(readme): lead with `molecule connect` for external workspaces		2026-04-30 07:49:19 -07:00
.claude	docs: add CLAUDE.md, known-issues.md, and .claude/settings.json (#2 )	2026-04-20 23:10:40 +00:00
.github/workflows	ci(release): switch release.yml to GoReleaser + race-detector tests	2026-04-30 05:30:31 -07:00
bin	fix(cli): align rootCmd.Use to goreleaser binary name	2026-04-22 05:36:07 +00:00
cmd/molecule	feat(cli): add --force flag to molecule init	2026-04-23 21:17:36 +00:00
internal	feat(connect): M1.3 — exec + claude-code backends	2026-04-30 04:23:36 -07:00
.gitignore	chore: gitignore credentials for molecule-cli	2026-04-16 09:18:55 -07:00
.goreleaser.yaml	ci(release): switch release.yml to GoReleaser + race-detector tests	2026-04-30 05:30:31 -07:00
CLAUDE.md	feat: implement full CLI command tree	2026-04-23 18:44:24 +00:00
go.mod	feat(connect): M1.1 — Backend interface + connect skeleton + mock backend	2026-04-30 02:05:12 -07:00
go.sum	feat: implement full CLI command tree	2026-04-21 01:18:24 +00:00
known-issues.md	feat: implement full CLI command tree	2026-04-23 18:44:24 +00:00
pr-description-draft-cli-full.md	fix(cli): align rootCmd.Use to goreleaser binary name	2026-04-22 05:36:07 +00:00
README.md	docs(readme): lead with `molecule connect` for external workspaces	2026-04-30 07:46:39 -07:00

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.

README.md Unescape Escape