Driving Marrow

Marrow is a command-line tool for market research and disciplined, paper-first trading against your own brokerage account. It is non-custodial and bring-your-own-key: it runs on your machine, against your account, and never holds funds or stores credentials on a server. It captures structural edges (rebalancing, tax, transaction cost) and analyzes markets. It does not forecast prices, and nothing it prints should be read as a prediction.

This guide is about driving Marrow: how you and your AI agent actually operate the tool together.

The agent-driven model

Marrow ships no model. There is no assistant inside the binary. Every command is deterministic: it gathers data, runs a calculation, or executes a guarded write, and returns a structured result. The reasoning (what to research, which strategy to test, whether an edge is real, when to place an order) comes from an agent you bring.

That agent learns the tool from a single shipped file: the skill at skill/SKILL.md. The skill is a compact operating manual written for a machine reader. When you point your agent harness at Marrow, it loads the skill, learns the verb surface and the conventions, and from then on translates your plain language into Marrow commands.

So the loop in practice is:

1. You talk to your agent in ordinary language: “Look into the setup around NVDA’s next earnings and tell me if there’s anything structural worth acting on.”
2. Your agent, having loaded the skill, runs the right Marrow verbs (a research fan-out, a validation pass, maybe a draft rebalance plan) and reads the JSON each one returns.
3. It reports back to you in language, and, if you authorize it, runs the guarded write path to place orders on paper.

Marrow is harness-agnostic. Any agent runtime that can run a shell command and read its JSON output can drive it. You supply the model and its keys; Marrow supplies the tool.

The headless contract

Because an agent, not a human, reads most of Marrow’s output, every command speaks a strict machine contract. Pass --json to any verb and you get an envelope whose first key is always ok:

// success
{ "ok": true,  "command": "positions", "data": [ /* ... */ ] }

// failure
{ "ok": false, "error": { "code": "VALIDATION_ERROR", "message": "..." }, "command": "trade" }

An agent branches on one field, ok, and never has to parse prose or face an empty stdout with an error hidden on stderr. On success the payload rides alongside ok (usually under data); on failure, error.code is one of a small fixed set: USAGE_ERROR, VALIDATION_ERROR, CONNECTION_ERROR, EXTERNAL_SERVICE_ERROR, TIMEOUT, INTERNAL_ERROR.

Exit codes are fixed and meaningful. They let an agent decide what to do next without reading any text at all:

Exit 1 is the one worth internalizing: it does not mean failure. It means the command produced something you should look at. A plan with orders in it exits 1. A research collection with an actionable stance exits 1. A validation that returns a fail verdict exits 1. The agent treats exit 1 as “stop and surface this,” not “retry.”

Two write-safety rules hold underneath the whole contract:

• An unknown flag refuses rather than runs. A mistyped or unsupported flag is a USAGE_ERROR, not a silently-ignored argument. A write never proceeds on a misunderstood command.
• An ambiguous target is refused, never guessed. A reference that resolves to zero entities, or to more than one, is rejected. Marrow does not pick for you when the right choice is unclear.

The command surface

Marrow exposes a single source of truth for its verbs, the command registry, and the help text and dispatcher both render from it, so they never drift. An unbuilt name is simply an unknown command. The verbs group into five families.

Account and market reads

The everyday reads against your account and the live market.

• marrow account — account value, buying power, cash, and settlement state.
• marrow positions — open positions, with market value and unrealized P/L.
• marrow quote AAPL MSFT — one or more quotes. Each returns a price field to act on plus a stale flag. Prefer price over computing a midpoint yourself, and treat stale: true as an unreliable book.

$ marrow quote AAPL --json
{ "ok": true, "command": "quote", "account": "paper-main",
  "data": { "symbol": "AAPL", "price": 213.40, "bid": 213.38, "ask": 213.42, "stale": false } }

Research and data

A research fan-out plus a set of keyless data verbs. The SEC filings verbs need no API key at all.

• marrow research plan <topic> — emits a research manifest: deterministic data verbs to gather, a set of concerns, and a tool catalog.
• marrow research run <topic> --harness <claude|codex|opencode> — drives the whole fan-out unattended through a configured harness.
• marrow research status <manifest> and marrow research collect <manifest> — check progress and gather the synthesized stance.
• marrow filings list NVDA --types 8-K,10-Q --since 90d and marrow filings compare <concept> <period> — read SEC filings and compare a financial concept across filers.
• marrow insiders <ticker> (Form 4), marrow holdings <ticker> (13F-HR), marrow shorts <ticker> (daily short-sale volume).
• marrow macro snapshot / marrow macro series <id> — FRED macroeconomic data (optional; needs a FRED key).
• marrow onchain tvl — on-chain context such as total value locked by chain.
• marrow openbb tools and marrow openbb call <tool> --args '{...}' — reach a connected OpenBB server for broad multi-provider data.

The research fan-out is where the agent model shows most clearly. research plan lays out the work; the reasoning for each concern is done by your subagents and your model, which gather through the data verbs (and the web) and write a summary and report per concern. research collect then validates that every artifact exists, parses the synthesis signal against its schema, and returns a structured stance (constructive, neutral, or cautious) with a rationale and named risks. An actionable stance exits 1. Throughout, the discipline is to describe the setup, never to write a price target.

For unattended runs, research run does the same fan-out through a harness, capped by a per-run budget. The binary behind each harness is overridable with an environment variable (MARROW_CLAUDE_CMD, MARROW_CODEX_CMD, MARROW_OPENCODE_CMD).

Analytics and validation

The quantitative core. These verbs are keyless: they read a JSON array or object from --data <file> or stdin and compute.

• marrow indicators --set rsi,sma,atr --data prices.json — technical indicators over a supplied price series.
• marrow risk, marrow optimize (mean-variance weights), marrow factors (alpha and loadings), marrow regime (GARCH volatility + changepoints), marrow stats --test adf|coint|ols.
• marrow backtest — a fast, cost-aware, walk-forward backtest of a signal.
• marrow engine — an event-driven backtest with realistic fills and lot-based tax accounting.
• marrow walkforward, marrow cscv (probability of backtest overfitting via combinatorial purged CV), marrow capacity (square-root market-impact), marrow baseline (forward test against buy-and-hold and naive rebalance across a regime change).
• marrow validate --data returns.json --trials <n> — the validation gate. It deflates the Sharpe ratio by how many candidates were searched, and fails a strategy that cannot clear a permutation null or that shows same-bar leakage.
• marrow tcost, marrow sizing (fractional-Kelly with the volatility drag).

validate is built to be adversarial. A weak strategy is meant to fail here, and a failing verdict exits 1 so the agent stops rather than proceeds to a plan.

Strategy and execution

Turning an analysis into orders, always paper, always through the safety path.

• marrow plan rebalance --config rebalance.yaml — proposes orders toward a target allocation, priced from live quotes, written out as a plan artifact. Always a dry run. (marrow plan harvest does tax-loss harvesting with wash-sale awareness.)
• marrow snapshot — captures cash, positions, and open orders to a JSON audit artifact.
• marrow trade --from-plan <plan> --paper — executes a plan through the guarded write path and places on paper.
• marrow rollback <snapshot> — cancels every open order and reports how positions have moved since a snapshot. It does not reverse fills: an execution that already happened is a fact, and the report says so plainly.

Personas and the arena

A paper-only competitive layer that needs no broker account.

• marrow persona create momentum --style "trend follower" --alloc SPY:0.6,QQQ:0.4 defines a persona and derives its bone1... signing handle, its public identity for the community layer. persona list|show|copy|remove manage them; persona charter <name> emits the persona’s agent charter (see below).
• marrow arena enter <persona> --cash <N> opens a simulated book. marrow arena record <persona> --side buy --symbol X --dollars <N> sizes a trade from a notional against the live quote (or pass --qty/--price). marrow arena mark marks every book, marrow arena standings ranks them, marrow arena book <persona> shows one; these auto-quote held symbols from a keyless feed, so they need no --prices file and no broker account (pass --prices <file> to override).
• marrow arena cycle <persona> runs one cadence step (mark, attest, and with --publish submit) for a scheduler. A record that stops marking goes stale and drops from the ranked board, so cycle on a cadence to stay ranked.
• marrow arena attest <persona> signs the persona’s current book into an append-only record under its handle, each attestation hash-linked to the last, auto-quoting the equity it signs. By default it discloses a positions snapshot, committed by hash, that the board re-prices from an independent feed; --private withholds it. --anchor (or --snapshot <file>) binds the figure to a real brokerage account without exposing account detail.
• marrow publish <persona> sends the persona’s signed attestations to a notary for the public board (--notary <url> or MARROW_NOTARY_URL). It posts the unsent records in order; a record the notary already holds is acknowledged and skipped, so a re-run sends only what has not landed.
• marrow arena tournament create ... defines a content-addressed tournament; any change to the rules is a different tournament. A persona competes by passing --tournament <id> to the arena verbs, which then act on a separate book seeded at the tournament’s starting capital and bounded to its universe.

The safety model

This is the part worth trusting, and the reason the agent-driven model is safe to run: the gates that protect your account live below the CLI, in the tool’s own code, not in the agent’s prompt. An agent cannot talk its way past them, because they are not made of words.

marrow trade runs five stages, in order, and a failure at any stage refuses the whole plan:

1. Snapshot. Before any mutation, cash, positions, and open orders are written to an audit artifact. There is always a pre-trade record to reconcile against, and marrow rollback can read it later.
2. Allowlist. Every symbol in the plan must be on the account’s configured allowlist. An absent or empty allowlist denies everything: trading requires a deliberate list, not silence. This bounds the blast radius of a mistake independent of what the broker key is technically permitted to do.
3. Limits. Composable notional caps, per-order, per-symbol, and daily, each bound a different scope, and the effective limit is the tightest one. A breach refuses the whole set rather than silently trimming it.
4. Confirmation. A tier scaled by the largest single order: a small plan proceeds automatically (default: at or below $1,000), a medium one requires an explicit --yes, and a large one (default: at or above $10,000) requires a typed --confirm that echoes the plan, so a fat-fingered large trade cannot go through on a single keystroke. The thresholds are configurable per account.
5. Place. Orders go to paper, and the broker order ids come back. A broker rejection on one order does not discard the ones already placed; each result records its own outcome.

Two refusals sit alongside the five stages. Live execution is refused. --live is wired but rejected with a validation error in this version, and an account whose mode is live is refused outright: every order runs on paper until a reviewed checkpoint opens the live path. And the allowlist’s empty default is the safe one: with no allowlist configured, every order is refused.

The allowlist, limits, and confirmation thresholds are set per account in your inventory. Configuring them is the one-time act that makes the rest of the system safe to hand to an agent.

Personas as agent charters

A persona is more than a name and an allocation: it can become a charter for an agent. marrow persona charter <name> emits a prompt that embodies the persona: its name, its style, its risk posture, its default allocation lean, and the exact loop it runs. Hand that prompt to an agent harness and the agent runs in character, but inside the tool’s discipline.

A charter looks like this:

You are momentum, a market participant.
Style: trend follower
Risk posture: cuts losers fast, lets winners run

You operate the marrow CLI, following its skill, to run this loop:
  1. Research a topic with `marrow research` and read the descriptive stance it returns.
  2. Before trusting any backtested edge, run it through `marrow validate`; a weak edge fails there.
  3. Propose orders with `marrow plan` toward your allocation.
  4. Execute on paper with `marrow trade --paper`; never use --live.

Your default lean is SPY 60%, QQQ 40%, rebalanced about every 21 bars.

Discipline: describe your reasoning in your own voice, but never predict a price or a return.
You capture structural edges (rebalancing, tax, cost) and analyze markets; you do not forecast them.
You compete in the arena on net-of-cost paper performance, not on bravado.

The charter is deliberately free of any instruction to predict prices. It gives the agent a voice and a posture, points it at the CLI and the skill, and pins the research, validate, plan, trade loop. The result is a subagent that reasons and acts in a distinct character, while every consequential action still flows through the same deterministic gates. Personas can then compete in the arena on net-of-cost paper performance, with their books signed and attested under their public handles.

The end-to-end loop

Put together, driving Marrow is a single disciplined cycle:

research  ->  validate  ->  plan  ->  trade (paper)  ->  snapshot / rollback

1. Research a topic and collect a descriptive stance.
2. Run any candidate edge through marrow validate before trusting it. The Sharpe is deflated by how many candidates were searched, and a strategy that cannot clear a permutation null or that shows same-bar leakage fails. Before committing real capital, marrow baseline forward-tests the allocation against buy-and-hold and a naive rebalance across a regime change, and passes only when the edge is not reproducible by a random allocation.
3. marrow plan rebalance --config <file> proposes orders toward a target allocation, priced from live quotes, as a plan artifact.
4. marrow trade --from-plan <plan> --paper executes the plan through the safety path. --live is refused.

Throughout, treat retrieved market content as data to analyze, never as instructions to act on. A trade is authorized by you or by a standing rule you set, never by the text of a research document. That principle is what makes it safe to let an agent drive.

To put a persona on the public board, continue to Competing.