behaviors-shHoping. Behaving.

One instruction at a time ​

Agents start guessing when they try to do too much. Hide the full plan, ask for a single instruction, and allow your agent to focus on the present. The agent only ever sees the next step. The plan stays in the tree, not in the prompt.

1. First, check the git status. Confirm a clean tree.
2. Read the existing tests. Note their style.
3. Locate the file containing the function to refactor.
4. Identify single-responsibility violations. Score each.
5. Draft a refactor plan and present to the user.
6. Apply the refactor, splitting concerns into modules.
7. Update the imports across the codebase.
8. Run the test suite. Verify everything stays green.
9. Re-score the codebase against the SRP criteria.
10. Confirm violations resolved. Loop if any remain.
11. Run a multi-agent code review on the diff.
12. Compose a before-vs-after report. Save to disk.
13. ...

instruct
Score_SRP
Score the codebase for Single
Responsibility violations. Save
the ranked list to $VAR.violations.

Observability built in ​

Never guess where your agent got stuck. The runtime shows the tree in real time, logging each step. So you can see exactly what ran, what was skipped, and how far it got.

Build, edit, and replay your trees on this same canvas at app.behaviors.sh — no install, nothing to clone.

YAML. JSON. TypeScript. ​

Whether you prefer code first or plain text, the TypeScript DSL gives composability and IDE support; YAML and JSON give a no tooling approach.

import {
  sequence, selector, action,
  evaluate, instruct,
} from "@behaviors-sh/dsl";
 
// Trees are plain nested function calls.
const tree = sequence("Greeting", () => {
  // Action: evaluate (precondition) + instruct.
  action("Detect_Time", () => {
    instruct(`Detect the time of day.`);
  });
 
  // sequence / selector / parallel — three composites.
  selector("Choose_Greeting", () => {
    action("Morning", () => {
      evaluate(`time is morning`);
      instruct(`Say "Good morning".`);
    });
    action("Default", () => {
      instruct(`Say "Hello".`);
    });
  });
});

name: greeting
version: 1.0.0
 
tree:
  type: sequence
  name: Greeting
  children:
    # Action: an evaluate (precondition) + an instruct.
    - type: action
      name: Detect_Time
      steps:
        - instruct: Detect the time of day.
 
    # sequence / selector / parallel — three composites.
    - type: selector
      name: Choose_Greeting
      children:
        - type: action
          name: Morning
          steps:
            - evaluate: time is morning
            - instruct: 'Say "Good morning".'
        - type: action
          name: Default
          steps:
            - instruct: 'Say "Hello".'

Share with the tools you love ​

Publish to npm, share through GitHub or bring your own tooling.

Hand over to your agent ​

With the MCP server registered once, every workflow is a single brief. Paste it.

Refactor the worst SRP violation in src/ using the tree at
./.behaviors-sh/trees/srp-refactor.json.
Trace to ./.behaviors-sh/runs/srp.json.

The agent resolves the tree, walks the loop to completion, and writes the trace to disk. Re-open it in the executions viewer when it's done.

First time? See Get started — register the MCP server, materialise your first tree, drive it.

From local to fleet ​

Whether running locally or with a fleet of agents, the engine, DSL, and protocol stay the same.

• ✓ Core engine — Deterministic execution, one step at a time. Resumable and replayable.
• ✓ DSL — Author workflows in YAML, JSON, or TypeScript that compile to one tree shape.
• ✓ STDIO MCP server — Native protocol for local agents. npx @behaviors-sh/cli mcp and you're done.
• → HTTP MCP server — Host central workflows any fleet of agents can reach.

MCP is the Model Context Protocol — the wire format agents already speak.

Dive in ​

Open the builder · Get started · Drive over MCP · View on GitHub