molecule-core/docs/tutorials/gemini-cli-runtime.md
claude-ceo-assistant 3501e6bfd7
Some checks failed
CodeQL / Analyze (${{ matrix.language }}) (go) (pull_request) Successful in 13s
CodeQL / Analyze (${{ matrix.language }}) (python) (pull_request) Successful in 11s
CodeQL / Analyze (${{ matrix.language }}) (javascript-typescript) (pull_request) Successful in 12s
Check merge_group trigger on required workflows / Required workflows have merge_group trigger (pull_request) Successful in 15s
Block internal-flavored paths / Block forbidden paths (pull_request) Successful in 27s
CI / Detect changes (pull_request) Successful in 20s
Retarget main PRs to staging / Retarget to staging (pull_request) Has been skipped
Lint curl status-code capture / Scan workflows for curl status-capture pollution (pull_request) Successful in 15s
E2E API Smoke Test / detect-changes (pull_request) Successful in 51s
E2E Staging Canvas (Playwright) / detect-changes (pull_request) Successful in 51s
Secret scan / Scan diff for credential-shaped strings (pull_request) Successful in 39s
Handlers Postgres Integration / detect-changes (pull_request) Successful in 51s
Harness Replays / detect-changes (pull_request) Successful in 53s
Runtime PR-Built Compatibility / detect-changes (pull_request) Successful in 48s
Ops Scripts Tests / Ops scripts (unittest) (pull_request) Successful in 1m7s
CI / Shellcheck (E2E scripts) (pull_request) Successful in 31s
Harness Replays / Harness Replays (pull_request) Failing after 1m18s
E2E API Smoke Test / E2E API Smoke Test (pull_request) Successful in 2m19s
Runtime PR-Built Compatibility / PR-built wheel + import smoke (pull_request) Successful in 3m14s
Handlers Postgres Integration / Handlers Postgres Integration (pull_request) Successful in 6m1s
E2E Staging Canvas (Playwright) / Canvas tabs E2E (pull_request) Successful in 6m47s
CI / Python Lint & Test (pull_request) Successful in 8m16s
CI / Canvas (Next.js) (pull_request) Failing after 9m36s
CI / Canvas Deploy Reminder (pull_request) Has been skipped
CI / Platform (Go) (pull_request) Successful in 12m18s
fix(post-suspension): vanity import paths go.moleculesai.app/core/{platform,tests/harness/cp-stub} (closes molecule-ai/internal#71 phase 2)
Migrates the two Go modules under molecule-core off the dead
github.com/Molecule-AI/molecule-monorepo/... identity onto the vanity
host go.moleculesai.app. Also fixes the historical naming
inconsistency where the Gitea repo is molecule-core but the Go module
path said molecule-monorepo.

Module changes:
- workspace-server/go.mod:
    github.com/Molecule-AI/molecule-monorepo/platform
    -> go.moleculesai.app/core/platform
- tests/harness/cp-stub/go.mod:
    github.com/Molecule-AI/molecule-monorepo/tests/harness/cp-stub
    -> go.moleculesai.app/core/tests/harness/cp-stub

Surfaces touched
- 174 *.go files (374 import lines) — every import under
  workspace-server/ + tests/harness/cp-stub/
- 2 Dockerfiles (workspace-server/Dockerfile + Dockerfile.tenant) —
  -ldflags strings updated in lockstep with the module rename so
  buildinfo.GitSHA injection still resolves correctly
- README + docs + scripts + comment URLs to git.moleculesai.app form
- NEW workspace-server/internal/lint/import_path_lint_test.go —
  structural lint gate rejecting future github.com/Molecule-AI/ or
  Molecule-AI/molecule-monorepo references. Identical template to the
  other migration PRs (plugin-gh-identity#3, molecule-cli#2,
  molecule-controlplane#32).

Cross-repo dep allowlist (documented in lint gate)
workspace-server requires molecule-ai-plugin-gh-identity, whose own
vanity migration is PR molecule-ai-plugin-gh-identity#3. Until that PR
merges + a tag is cut at go.moleculesai.app/plugin/gh-identity, the
two locations referencing the legacy github.com path
(workspace-server/go.mod require, cmd/server/main.go import) remain
allowlisted. Follow-up PR drops the allowlist + updates both refs in
one shot once gh-identity is fully migrated.

Test plan
- go build ./... clean for both modules
- go test ./... green except two pre-existing failures
  (TestStartSweeper_RecordsMetricsOnSuccess flaky-on-suite,
  TestLocalResolver_BubblesUpCopyFailure relies on read-only fs perms
  but runs as root on operator host) — both reproduce identically on
  baseline main pre-migration; NOT regressions of this PR
- Mutation-tested: lint gate fails on canaries in .go + .md;
  allowlist correctly suppresses cross-repo dep references in go.mod
  while still flagging unrelated additions

Open dependency
- go.moleculesai.app responder must be deployed before fresh-clone
  external builds resolve the vanity path. Existing CI / Docker builds
  ride pinned go.sum + self-referential module path + responder is
  not on critical path for those.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-05-07 22:37:42 +00:00

2.8 KiB

Running a Gemini CLI Workspace on Molecule AI

Molecule AI now ships a gemini-cli runtime adapter alongside the existing claude-code adapter. This tutorial walks you from zero to a running Gemini agent workspace in under five minutes.

What you'll need

  • A Molecule AI account with at least one provisioned tenant
  • A Google GEMINI_API_KEY (get one at aistudio.google.com)
  • The Molecule AI CLI (pip install molecule-ai)

Setup (10 steps)

# 1. Install / upgrade the CLI
pip install --upgrade molecule-ai

# 2. Authenticate
molecule auth login

# 3. Store your Gemini API key as a global secret
molecule secrets set GEMINI_API_KEY="YOUR_KEY_HERE" --global

# 4. Create a gemini-cli workspace
molecule workspace create my-gemini-agent --runtime gemini-cli

# 5. Confirm it's running (status → "ready" within ~30 s)
molecule workspace status my-gemini-agent

# 6. Send your first task
molecule workspace run my-gemini-agent "Summarise the last 5 git commits in this repo"

# 7. View the streamed response
molecule workspace logs my-gemini-agent --follow

# 8. Check the agent's memory file (GEMINI.md)
molecule workspace exec my-gemini-agent cat GEMINI.md

# 9. Delegate a cross-workspace task to your new Gemini peer
molecule workspace run orchestrator "delegate_task my-gemini-agent 'Draft release notes for v1.4'"

# 10. Tear down when done
molecule workspace delete my-gemini-agent

Expected output

After step 5 you should see:

my-gemini-agent  gemini-cli  ready   ord   2026-04-16T06:30:00Z

After step 6, Gemini CLI streams its reasoning and final answer directly to stdout. The agent uses GEMINI.md (seeded from your workspace's system-prompt.md) as persistent context — equivalent to CLAUDE.md for Claude Code workspaces.

How it works

Molecule AI's gemini-cli adapter mirrors the battle-tested claude-code pattern: a Docker image installs @google/gemini-cli globally, and CLIAgentExecutor drives the subprocess. Because Gemini CLI reads MCP config from ~/.gemini/settings.json rather than accepting a --mcp-config flag, the adapter's setup() method merges the A2A MCP server definition into that file at boot — preserving any user-defined tools.

Multi-provider teams

The real power surfaces when you mix runtimes on the same Molecule AI tenant. Your orchestrator workspace can delegate tasks to both claude-code and gemini-cli workers simultaneously using delegate_task_async, then synthesize results — all through the same A2A protocol. This is provider diversity at the infrastructure layer, not at the application layer.