documentation-specialist 2ee3b42d6b docs(install): document upcoming Go-module migration + replace install command (#37 )

This PR is README-only. The Go module-path migration
(github.com/Molecule-AI/molecule-cli → git.moleculesai.app/molecule-ai/
molecule-cli in go.mod + every internal import) is filed separately as
a cross-repo Go-module migration PR (parked follow-up on internal#37).

Changes here:
- Install section: keep the go install command but switch to the
  Gitea path + add a "Migration in progress" callout pointing at the
  build-from-source workaround until the Go-module PR lands.
- Releases link: removed the broken github.com/.../releases URL
  (releases pipeline being restored on Gitea Actions).
- RFC #10 link: rewritten to git.moleculesai.app form with note that
  the original issue lived on the suspended GitHub org.

Files NOT touched in this PR (left for the cross-repo Go-module PR):
- go.mod (module declaration)
- 25+ .go files with github.com/Molecule-AI/molecule-cli/internal/...
  import paths
- known-issues.md L96 (describes current module path; consistent with
  go.mod)
- CLAUDE.md L37 (declares current module path; consistent with go.mod)

These edits maintain consistency with go.mod while documenting the
upcoming change to users. Bundling them with the doc edit would create
a half-state where docs say one path and go.mod says another.

Refs: molecule-ai/internal#37, molecule-ai/internal#38

2026-05-06 23:32:47 -07:00

3.5 KiB

Raw Permalink Blame History

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

Migration in progress (2026-05-07): the github.com/Molecule-AI org was suspended on 2026-05-06 and is permanently gone. The canonical SCM is now Gitea at git.moleculesai.app/molecule-ai.

The go install path below requires the Go module-path migration to land first (separate cross-repo PR — see internal#37 parked follow-up). Until then, build from source:
git clone https://git.moleculesai.app/molecule-ai/molecule-cli.git
cd molecule-cli
go build -o molecule ./cmd/molecule
Once the Go module-path migration lands:

go install git.moleculesai.app/molecule-ai/molecule-cli/cmd/molecule@latest

Releases ship Linux/macOS/Windows × amd64/arm64 archives plus a sha256 checksums file (see .goreleaser.yaml). Releases pipeline (Gitea Actions) is being restored as part of the post-suspension recovery; in the interim, build from source per the migration note above.

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 (originally filed on the suspended GitHub org; the issue may be re-filed on Gitea — check the issue tracker for the live discussion).

3.5 KiB Raw Permalink Blame History Unescape Escape