meridian-cli 0.3.26__tar.gz → 0.3.28__tar.gz

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/.gitignore

@@ -47,3 +47,4 @@ src/meridian/pi_runtime/.meridian/
 
 # Agent coordination scratch
 plan/
+.work-artifacts/

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: meridian-cli
-Version: 0.3.26
+Version: 0.3.28
 Summary: Orchestrate CLI + MCP server for multi-model agent workflows
 Project-URL: Homepage, https://github.com/haowjy/meridian-cli
 Project-URL: Repository, https://github.com/haowjy/meridian-cli
@@ -24,7 +24,7 @@ Requires-Dist: coolname>=4.0.0
 Requires-Dist: cyclopts>=3.0
 Requires-Dist: fastapi>=0.115
 Requires-Dist: markdown-it-py>=4.0
-Requires-Dist: mars-agents==0.10.2
+Requires-Dist: mars-agents==0.10.3
 Requires-Dist: mcp>=1.0
 Requires-Dist: pathspec>=1.1.0
 Requires-Dist: psutil>=7.2.2
@@ -48,19 +48,25 @@ Provides-Extra: templates
 Requires-Dist: jinja2>=3.1; extra == 'templates'
 Description-Content-Type: text/markdown
 
-# meridian
+# meridian-cli
 
-Orchestrate AI coding agents across Claude Code, Codex, and OpenCode. Each model runs through its native harness — meridian coordinates between them.
+Let coding harnesses call each other. meridian-cli lets agents running in Claude Code, Codex CLI, and OpenCode spawn named specialist agents in the other harnesses, each with the model, cost, and tool environment you configured.
 
-> **Early development.** Meridian is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
+It is for people who already use more than one AI coding CLI and want one team of agents instead of separate chat sessions.
+
+> **Early development.** meridian-cli is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
 
 ## Why
 
-Claude Code is (supposed to be) the best way to run Claude. Codex CLI is often the best way to run GPT. Each provider's harness is optimized for their models — sandboxing, tool use, context handling, everything (supposedly).
+Good agentic coding is an allocation problem. Some tasks need the strongest model you have; some need cheap, parallel throughput; some need a specific harness feature such as sandboxing, tool behavior, context handling, or integrations.
+
+Without meridian-cli, those choices are trapped inside separate CLIs. Switching harnesses means manually copying context between sessions and hoping the next agent understands what happened.
 
-But you can only use one at a time.
+meridian-cli turns that handoff into a command. A caller can delegate to a named specialist, pass only the context that agent needs, and pick up the result from disk. Use the expensive model where judgment matters, use cheaper agents where throughput matters, and keep every agent inside the harness that fits the job.
 
-Meridian lets agents spawn other agents across harnesses. The right model for each task, through the right runtime, with clean context per spawn.
+## One Harness Can Call Another
+
+> **Demo placeholder:** add a short terminal recording or screenshot here showing one coding harness spawning an agent in another harness, then collecting the result with `meridian spawn wait` or `meridian spawn show`.
 
 ## Install
 
@@ -68,6 +74,8 @@ Meridian lets agents spawn other agents across harnesses. The right model for ea
 uv tool install meridian-cli
 ```
 
+The package is `meridian-cli`; the command it installs is `meridian`.
+
 <details>
 <summary>Other methods</summary>
 
@@ -90,7 +98,7 @@ You need at least one harness installed: [Claude Code](https://docs.anthropic.co
 
 ## Set Up a Project
 
-`meridian init` by itself only bootstraps Meridian project config:
+`meridian init` by itself only bootstraps meridian-cli project config:
 
 ```bash
 meridian init

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/README.md

@@ -1,16 +1,22 @@
-# meridian
+# meridian-cli
 
-Orchestrate AI coding agents across Claude Code, Codex, and OpenCode. Each model runs through its native harness — meridian coordinates between them.
+Let coding harnesses call each other. meridian-cli lets agents running in Claude Code, Codex CLI, and OpenCode spawn named specialist agents in the other harnesses, each with the model, cost, and tool environment you configured.
 
-> **Early development.** Meridian is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
+It is for people who already use more than one AI coding CLI and want one team of agents instead of separate chat sessions.
+
+> **Early development.** meridian-cli is not stable. Expect breaking changes in any release. If you need a stable workflow, this project is not ready for you yet.
 
 ## Why
 
-Claude Code is (supposed to be) the best way to run Claude. Codex CLI is often the best way to run GPT. Each provider's harness is optimized for their models — sandboxing, tool use, context handling, everything (supposedly).
+Good agentic coding is an allocation problem. Some tasks need the strongest model you have; some need cheap, parallel throughput; some need a specific harness feature such as sandboxing, tool behavior, context handling, or integrations.
+
+Without meridian-cli, those choices are trapped inside separate CLIs. Switching harnesses means manually copying context between sessions and hoping the next agent understands what happened.
 
-But you can only use one at a time.
+meridian-cli turns that handoff into a command. A caller can delegate to a named specialist, pass only the context that agent needs, and pick up the result from disk. Use the expensive model where judgment matters, use cheaper agents where throughput matters, and keep every agent inside the harness that fits the job.
 
-Meridian lets agents spawn other agents across harnesses. The right model for each task, through the right runtime, with clean context per spawn.
+## One Harness Can Call Another
+
+> **Demo placeholder:** add a short terminal recording or screenshot here showing one coding harness spawning an agent in another harness, then collecting the result with `meridian spawn wait` or `meridian spawn show`.
 
 ## Install
 
@@ -18,6 +24,8 @@ Meridian lets agents spawn other agents across harnesses. The right model for ea
 uv tool install meridian-cli
 ```
 
+The package is `meridian-cli`; the command it installs is `meridian`.
+
 <details>
 <summary>Other methods</summary>
 
@@ -40,7 +48,7 @@ You need at least one harness installed: [Claude Code](https://docs.anthropic.co
 
 ## Set Up a Project
 
-`meridian init` by itself only bootstraps Meridian project config:
+`meridian init` by itself only bootstraps meridian-cli project config:
 
 ```bash
 meridian init

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/pyproject.toml

@@ -24,7 +24,7 @@ dependencies = [
   "cyclopts>=3.0",
   "fastapi>=0.115",
   "markdown-it-py>=4.0",
-  "mars-agents==0.10.2",
+  "mars-agents==0.10.3",
   "mcp>=1.0",
   "pathspec>=1.1.0",
   "psutil>=7.2.2",

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/src/meridian/__init__.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.3.26"
+__version__ = "0.3.28"

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/src/meridian/cli/command_groups.py

@@ -49,8 +49,8 @@ _GROUP_HELP: dict[str, GroupHelp] = {
         summary='Run subagents with a model and prompt file.',
         long_help='Hand a task to a subagent — a bulk read, a parallel fix, or a job for a stronger or cheaper model — so you keep your own context for the parts that need your judgment. Write the task to a file and pass --prompt-file; add --bg to launch detached and collect the result with `meridian spawn wait`.',
         examples=(('meridian spawn -m gpt-5.3-codex --prompt-file "$(meridian work path prompts/fix-auth.md)" --bg', ''), ('meridian spawn -m claude-sonnet-4-6 --prompt-file "$(meridian work path prompts/review.md)" --bg -f src/main.py', ''), ('meridian spawn --fork c123 --prompt-file "$(meridian work path prompts/follow-up.md)" --bg', ''), ('meridian spawn --fork-fresh c123 -a reviewer --prompt-file "$(meridian work path prompts/role-shift.md)" --bg', ''), ('meridian spawn wait', '')),
-        agent_notes="Core loop: launch detached with --bg, then drain with no-arg `meridian spawn wait`. Every --bg spawn must be drained before you respond to the user, start dependent work, or end your turn; un-waited background spawns are lost.\n\nLifecycle: queued → running → finalizing → terminal. Treat finalizing as active; terminal is succeeded, failed, cancelled, or timed_out.\n\nPrompt passing: use --prompt-file for delegation. Inline -p is for trivial smoke tests only because shell quoting mutates prompts ($vars, backticks, quotes, multiline) before meridian sees them. Run `meridian work path prompts/<name>.md`, write the prompt to the printed absolute path, then pass that path literally to --prompt-file. Disposable launch prompts belong under prompts/ (no /tmp, no shell var that won't survive the next Bash call).\n\nProfile vs model: prefer -a <profile> when a role fits; use -m <model> for one-offs. Put recurring model choices in profiles or config, not hardcoded spawn commands.\n\nContext refs: prefer a folder over a file bundle. A folder tells the agent where to work; it does not inline everything. Normal shape: one folder plus at most one source-of-truth file. AGENTS.md and .context/CONTEXT.md auto-load from the work directory, so don't pass them redundantly. Use --from for prior reasoning that is not in files.\n\n--goal is a verifiable exit state, not a restatement of the task.\n\nParallel work: launch several --bg spawns, then one no-arg `meridian spawn wait` drains all. Don't babysit with repeated `spawn show` or `session log`; wait when you need results.\n\nReuse decision: --continue resumes the same session; --fork branches while preserving identity; --fork-fresh branches and allows identity changes, with weaker cache locality; --from starts fresh while carrying prior context as reference.\n\nInspect a run: `meridian session log <id>`; use `meridian spawn children <id>` to trace descendants.\nSteer a running spawn: `meridian spawn inject`.\nStage spawn changes: `meridian spawn files <id> | xargs git add`.",
-        agent_notes_brief='Delegate with --prompt-file, never inline -p. The shell mangles a prompt before meridian sees it — backticks run as commands, $vars expand, quotes and newlines collapse. A file preserves exact text and keeps the handoff inspectable. Run `meridian work path prompts/<name>.md`, write there, then pass that path literally (no /tmp, and no $f shell var that won\'t survive your next Bash call):\n  meridian spawn -a coder --prompt-file "$(meridian work path prompts/task.md)" --bg\n\nPick the runner: -a <profile> when a role fits, -m <model> for a one-off. Keep recurring model choices in profiles or config, not in the command.\n\nPass context as a folder, not a file pile. A folder says where to work and lets the agent read what it needs; each extra -f may get inlined and drains its context. Usual shape: one folder plus at most one source-of-truth file. AGENTS.md and .context/CONTEXT.md auto-load from the work dir — don\'t re-pass them. Use --from for prior reasoning that isn\'t in any file.\n\nSet --goal to a verifiable exit state ("tests pass, lint clean"), not a restatement of the task — it\'s the contract the agent works until it meets.\n\nGoing parallel? Launch several --bg and let one `wait` drain them all; don\'t babysit with repeated `spawn show` / `session log` — that spends your context supervising instead of working.\n\nReuse a session with --continue. Full methodology and every flag — including --fork / --fork-fresh — is in `meridian spawn -h --advanced`.',
+        agent_notes="Core loop: launch detached with --bg, then drain with no-arg `meridian spawn wait`. Every --bg spawn must be drained before you respond to the user, start dependent work, or end your turn; un-waited background spawns are lost.\n\nLifecycle: queued → running → finalizing → terminal. Treat finalizing as active; terminal is succeeded, failed, cancelled, or timed_out.\n\nPrompt passing: use --prompt-file for delegation. Inline -p is for trivial smoke tests only because shell quoting mutates prompts ($vars, backticks, quotes, multiline) before meridian sees them. Run `meridian work path prompts/<name>.md`, write the prompt to the printed absolute path, then pass that path literally to --prompt-file. Disposable launch prompts belong under prompts/ (no /tmp, no shell var that won't survive the next Bash call).\n\nProfile vs model: prefer -a <profile> when a role fits; use -m <model> for one-offs. Put recurring model choices in profiles or config, not hardcoded spawn commands.\n\nContext refs: prefer a folder over a file bundle. A folder tells the agent where to work; it does not inline everything. Normal shape: one folder plus at most one source-of-truth file. AGENTS.md and .context/CONTEXT.md auto-load from the work directory, so don't pass them redundantly. Use --from for prior reasoning that is not in files.\n\nTask dir: source edits run in the work item's task_dir (check: `meridian task-dir`). --task-dir points one spawn at another checkout, e.g. a worktree lane; `meridian work task-dir <path>` rebinds the work item itself.\n\n--goal is a verifiable exit state, not a restatement of the task.\n\nParallel work: launch several --bg spawns, then one no-arg `meridian spawn wait` drains all. Don't babysit with repeated `spawn show` or `session log`; wait when you need results.\n\nReuse decision: --continue resumes the same session; --fork branches while preserving identity; --fork-fresh branches and allows identity changes, with weaker cache locality; --from starts fresh while carrying prior context as reference.\n\nInspect a run: `meridian session log <id>`; use `meridian spawn children <id>` to trace descendants.\nSteer a running spawn: `meridian spawn inject`.\nStage spawn changes: `meridian spawn files <id> | xargs git add`.",
+        agent_notes_brief='Delegate with --prompt-file, never inline -p. The shell mangles a prompt before meridian sees it — backticks run as commands, $vars expand, quotes and newlines collapse. A file preserves exact text and keeps the handoff inspectable. Run `meridian work path prompts/<name>.md`, write there, then pass that path literally (no /tmp, and no $f shell var that won\'t survive your next Bash call):\n  meridian spawn -a coder --prompt-file "$(meridian work path prompts/task.md)" --bg\n\nPick the runner: -a <profile> when a role fits, -m <model> for a one-off. Keep recurring model choices in profiles or config, not in the command.\n\nPass context as a folder, not a file pile. A folder says where to work and lets the agent read what it needs; each extra -f may get inlined and drains its context. Usual shape: one folder plus at most one source-of-truth file. AGENTS.md and .context/CONTEXT.md auto-load from the work dir — don\'t re-pass them. Use --from for prior reasoning that isn\'t in any file.\n\nSource edits run in the work item\'s task_dir — check it with `meridian task-dir`. Pass --task-dir to point one spawn at another checkout (e.g. a worktree lane); rebind the work item itself with `meridian work task-dir <path>`.\n\nSet --goal to a verifiable exit state ("tests pass, lint clean"), not a restatement of the task — it\'s the contract the agent works until it meets.\n\nGoing parallel? Launch several --bg and let one `wait` drain them all; don\'t babysit with repeated `spawn show` / `session log` — that spends your context supervising instead of working.\n\nReuse a session with --continue. Full methodology and every flag — including --fork / --fork-fresh — is in `meridian spawn -h --advanced`.',
         agent_subcommands=('show', 'wait', 'list', 'children', 'files', 'report', 'inject', 'done', 'rearm', 'cancel', 'cancel-all'),
         agent_core_subcommands=('wait', 'show', 'list', 'inject', 'files', 'cancel'),
     ),

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/src/meridian/cli/spawn.py

@@ -337,10 +337,11 @@ def _spawn_create(
         str | None,
         Parameter(
             name="--task-dir",
-            group=ADVANCED_PARAMS,
             help=(
                 "Override the source-code edit directory for this spawn only. "
-                "Does not modify the work item's task_dir setting. "
+                "Does not modify the work item's task_dir setting "
+                "(check with `meridian task-dir`; rebind with "
+                "`meridian work task-dir <path>`). "
                 "Relative -f paths resolve against this directory."
             ),
         ),

{meridian_cli-0.3.26 → meridian_cli-0.3.28}/src/meridian/lib/launch/spawn_guidance.py

@@ -17,10 +17,17 @@ Every spawn starts with fresh context — scope the handoff to what the \
 subagent needs, not what you've been thinking about. Front-load the task; \
 the subagent should know its job by line 3.
 
-Pass `--skills skill1,skill2` to load additional skills onto the subagent.
-Agent profiles already set the right model for each role; prefer the \
-defaults. Use `-m <model>` only for deliberate fan-out (e.g. reviewers \
-across models for perspective diversity).
+Compose the lane at spawn time:
+- `--skills skill1,skill2` attaches focus skills to any agent — prefer a
+  near-fit agent plus an attached skill over a generic agent.
+- `-m <model>` overrides the profile model — for deliberate fan-out (the
+  same task across models) or when the lane needs a capability the
+  default lacks; otherwise prefer the profile default.
+- `--from <spawn-or-chat id>` hands the spawn a prior conversation's
+  context — reach for it when the reasoning matters, not just the
+  artifacts (knowledge capture, reviewing a decision trail).
+- `--task-dir <path>` points the spawn's source edits at another
+  checkout, e.g. a worktree lane that must not collide with others.
 
 For model-specific prompting guidance:  meridian mars models prompting <agent-or-model>"""
 
@@ -57,18 +64,15 @@ def build_spawn_usage_contract(variants: SpawnUsageContractVariants) -> str:
 - Do NOT use the Agent() tool for work that a meridian agent can do.
   Use `meridian spawn -a <agent>` instead — it routes to the right
   model and harness, tracks the work, and produces inspectable artifacts.
-- Launch with --bg; it returns a spawn id without waiting for the work and
-  runs the worker detached:
-      meridian spawn -a <agent> --prompt-file <prompt>.md --bg
 - {variants.double_wrap_bullet}
 - {variants.timeout_bullet}
-- Track with no-arg wait — no id needed; it discovers your pending spawns
-  by session and yields cache-cleanly. Re-invoke to keep waiting:
-      meridian spawn wait
-- Every --bg spawn must be drained with `meridian spawn wait` before you
-  respond to the user, start dependent work, or end your turn; un-waited
-  background spawns are lost.
-- Full reference:  meridian spawn -h"""
+- Drain every --bg spawn with no-arg `meridian spawn wait` before you
+  respond to the user, start dependent work, or end your turn. It finds
+  your pending spawns by session; re-invoke to keep waiting. The wait
+  itself can run in your native background execution to keep working
+  while it blocks — it's the launch, not the wait, that must never be
+  background-wrapped. Un-waited background spawns are lost.
+- Playbook and full flags:  meridian spawn -h"""
 
 
 def has_spawn_capability(profile: AgentProfile | None) -> bool: