Skip to content

Quickstart

Getting started

Two ways in

There are two entry points by design. TypeScript is the reference implementation, the package you embed in an agent; it carries the spec, the validator, and the MCP server. Rust is the default native CLI, a single fast binary for the command line with no runtime to install.

Install

TypeScript (embed the library)

The package is on the public npm registry, so it installs with no token:

npm install @corvidlabs/agent3md
import { Agent, validateAgent } from "@corvidlabs/agent3md";
import { readFileSync } from "node:fs";

const src = readFileSync("agent.3md", "utf8");
console.log(validateAgent(src).ok);                  // true
const agent = new Agent(src);
const top = agent.route("find every TODO")[0].skill; // -> "search"
console.log(agent.command(top.name, { pattern: "TODO", path: "src" }));
// -> rg --line-number 'TODO' 'src'   (route -> fill -> run)

Rust (the native CLI)

A fast native binary, nothing to run it on top of:

cargo install agent3md

Scaffold a new agent

The CLI's new command writes a valid starter agent with two real command-backed skills. From a clone of the repo:

git clone https://github.com/CorvidLabs/agent-3md && cd agent-3md
bun run cli new my-agent          # writes my-agent.3md (default <name>.3md)

This produces a conforming my-agent.3md with an identity plane plus search (backed by rg) and json (backed by jq) skills, and prints the next commands to try.

Validate

Always validate after editing. The validator exits non-zero on any error, so it drops straight into CI:

bun run validate my-agent.3md      # TypeScript
agent3md validate my-agent.3md     # Rust

A passing run reports PASS with the error and warning counts.

Route and run a request

The run command does the whole loop: it routes the request, fills the chosen skill's command from k=v inputs, and prints the exact command.

bun run cli run my-agent.3md "find every TODO" pattern=TODO path=src
request: "find every TODO"
  -> search  (matched: find)
  command: rg --line-number 'TODO' 'src'

If you leave an input out, the command is still printed with the placeholder visible and a fill: line tells you what is missing.

Actually run it with --exec

Add --exec to execute the produced command. Every referenced placeholder must have a value, or --exec refuses to run:

bun run cli run my-agent.3md "find every TODO" pattern=TODO path=src --exec

The same works with the Rust binary:

agent3md run my-agent.3md "find every TODO" pattern=TODO path=src
agent3md run my-agent.3md "find every TODO" pattern=TODO path=src --exec

Serve it over MCP

To expose the agent's skills to any MCP-capable client:

bun run mcp my-agent.3md

See MCP server for client configuration, and the CLI reference for every command.