Agent Integration | ONDE Docs

Goal

Wire any LLM or framework. Zero SDK. Zero daemon. Terminal pipes. Predictable loop.

10.1 The Core Agent Loop

Agent never runs background service. Agent never touches hidden database.
Loop stays identical every time:

1. Agent writes/edits .md files (any editor, any script)
2. Run `onde lint` → syncs, fixes IDs, validates, updates files
3. Run `onde find` or `onde q` → reads exact state
4. Run `onde git commit` → locks changes
5. Repeat

Idempotent. Safe. Works offline. Works with any model.

10.2 Wire Any LLM (CLI Pipes)

onde outputs text. LLMs read text. Pipe connects them.

# Feed blocked tasks to local model
onde find task --status BLOCKED --format json | ollama run llama3 "prioritize these"

# Feed compact outline to cloud API
onde find task --format md-dense | curl -X POST https://api.yourmodel.com/v1/chat ...

# Get reasoning back, write to file, sync
echo -e "## New Decision\ntype:: decision\nconfidence:: 0.8" >> decisions/new.md
onde lint

Format rule:

json → scripts, APIs, code agents
md-dense → context windows, reasoning models
md → round-trip edits, human review

10.3 Prompt Rules (`SOUL.md`)

Agents need boundaries. Put rules in workspace root. Name it SOUL.md or AGENT.md.
Agent reads file once. Follows steps. Zero guesswork.

## Workspace Rules
- Write markdown. Use `key:: value` or dense blocks.
- After every edit: run `onde lint`.
- Before work: run `onde find task --status TODO --sort priority`.
- Never guess IDs or links. Use `onde find` to locate nodes first.
- Commit with `onde git commit`.
- If lint fails: read error line, fix file, run lint again.
- Do not edit query results unless `--fields` is present.

Keep it short. Agent follows it. Workspace stays clean.

10.4 Framework Setup

No plugin needed. Framework calls terminal. onde returns text.

Framework	Setup
Claude Code / Cursor / Windsurf	Add `onde` to allowed shell commands. Point agent to `SOUL.md`. Agent runs CLI, reads stdout, writes MD.
OpenClaw / Hermes	Define tool: `exec: onde find $args`. Parse JSON/MD output. Write result to `.md`. Run `onde lint`.
Custom Python/JS Agent	`subprocess.run(["onde", "find", "task", "--format", "json"])`. Parse stdout. Write MD. Call `onde lint`.
MCP Servers	Expose three tools: `onde_lint`, `onde_find`, `onde_query`. Input = CLI flags. Output = stdout text. Agent calls tool → gets data → continues.

Rule: Framework = wrapper. onde = engine. Keep wrapper thin. Parse stdout. Write MD. Call lint. Done.

10.5 Common Agent Workflows

Planning

onde find task --status TODO --sort priority --limit 5 --format md-dense
# Agent picks top item → writes task MD → runs `onde lint` → commits

Dependency Check

onde deps task-882 --format lines
# Agent sees chain → updates plan → writes decision → runs `onde lint`

Failure Recovery

onde find decision --status REJECTED --format md
# Agent reads past mistakes → changes approach → writes new decision → lints

Daily Sync

git pull
onde lint
onde find task --status BLOCKED --format table
# Agent reads dashboard → picks work → edits MD → lints → commits → pushes

10.6 Traps & Fixes

Trap	Symptom	Fix
Agent edits query result without `--fields`	Changes vanish next lint	Add `--fields` to query. Enables bidirectional sync.
Agent guesses links	`[[maybe-task]]` breaks lint	Run `onde find` first. Use exact ID or full title.
Agent skips lint	Graph stale. Queries return old data.	Enforce `onde lint` after every write. Add to `SOUL.md`.
Agent overwrites `SOUL.md`	Rules lost next run	Lock file or add to version control. Agent reads, never writes.
Framework hangs on large output	Context overflow. Slow response.	Use `--limit N` or `--format md-dense`. Trim context.
Agent writes invalid enum	Lint fails. Blocks pipeline.	Run `onde find task --format json` first. Read valid values from schema or existing nodes.

10.7 Why This Beats Vector Memory

Vector search guesses from text similarity. Returns fuzzy matches. Burns tokens.
onde returns exact rows. Typed. Filtered. Sorted.
Agent asks for status=BLOCKED. Gets only blocked. Zero noise. Zero guesswork.
Replace semantic diary with terminal queries. Context window stays clean. Reasoning stays sharp.

Next Step: → Troubleshooting & Reference