Also available as Markdown on GitHub. Example code available here.

Hooks make the agent workflow programmable. If you’ve ever reminded an agent twice to avoid a file, run a test, or follow a release rule, you have already found a use case for hooks.

Hooks enable this by attaching user-defined handlers to specific lifecycle points in an agent session. A handler receives event data, can be narrowed by an optional matcher or filter, and can return context, make a decision, or perform a side effect.

The main value proposition is deterministic control: rules already captured in scripts, tests, policy checks, and runbooks can run at known lifecycle points in the agent workflow instead of depending on the model to remember and voluntarily follow them.

Use prompts for guidance. Use hooks for behavior that should run every time.

For example, a project instruction can say “do not edit generated files,” but a PreToolUse hook can inspect the attempted edit and block it before it happens; a project instruction can say “run tests before finishing,” but a PostToolUse hook can run the test suite after edits and a Stop hook can prevent completion when the last test run failed.

This post uses six lifecycle points that cover the main flow developers usually need first, using the canonical hook names as shorthand:

• SessionStart: load session context, such as project conventions, active constraints, environment facts, or a relevant runbook when the session starts.

• UserPromptSubmit: inspect the user prompt before the model sees it, then add context, route the request, or block a known-bad prompt.

• PreToolUse: inspect a tool call before it runs and block, approve, or modify behavior based on project policy.

• PostToolUse: run validation after a successful tool call, such as tests, formatting, scanning, logging, or state capture.

• Stop: check whether the agent should be allowed to finish the turn.

• SessionEnd: write final logs, flush metrics, export a summary, or clean up temporary state when the session ends.

Other hooks exist and are worth learning later, but these are a good starting set because they cover the main flow: start the session, receive the prompt, attempt an action, validate the action, finish the turn, and close the session.

The operating model

The simplest mental model is:

event → optional matcher/filter → handler → outcome

An event is a lifecycle moment, like `PreToolUse` or `Stop`.

An optional matcher or filter narrows when the hook should run, such as only for shell commands or only for file edits. When no matcher is needed, the handler runs for that lifecycle event.

A handler is the action the hook takes: depending on the runtime, that might be a shell command, HTTP request, MCP tool call, LLM prompt, or subagent. This demo uses command handlers because shelling out to Python scripts is the most portable option across tools.

The outcome is the returned context, decision, log entry, or state update.

A hook doesn’t make the entire agent run deterministic. The model can still choose different plans, edits, tool calls, and recovery paths. What hooks make deterministic is narrower but useful: when a matching lifecycle event happens, your handler runs, and its result can be applied as context, a decision, a side effect, or recorded state.

Even that depends on the handler. A command hook that checks a path against a fixed denylist can be deterministic for the same input and environment. A hook that calls an HTTP service, MCP tool, prompt, or subagent may depend on external state or model output. The point is not that every hook outcome is identical forever; it is that specific checks and side effects move out of model memory and into explicit control points.

That separation is useful because open-ended reasoning and deterministic checks belong in different places. Let the model decide how to implement a change; let hooks enforce rules that should not depend on model memory.

Why are hooks underutilized?

Hooks are underutilized because teams usually just start by adding more prompt instructions, and prompt instructions are easier to see than lifecycle automation. Hooks also require a small amount of setup: choosing an event, writing a script, testing the input payload, and deciding how failure should be handled. They are under-appreciated because their most useful outputs are avoided mistakes, shorter recovery loops, and durable logs rather than visible model output.

That setup pays for itself when the rule is specific and repeatable. Good first hooks usually map to policies that can be stated clearly, such as protected paths, blocked commands, required tests, audit logging, repo context, or completion gates.

A useful rule of thumb is simple: when a requirement says “always,” “never,” “block,” “record,” “run,” or “verify,” it probably belongs in a hook rather than only in a prompt.

A practical demo

The rest of this post walks through concrete hook examples: what each lifecycle point is useful for, what the hook receives, and how it can return context, block an action, or record state.

This post includes a companion demo in `agent-hooks-demo/`: a small checkout calculator that totals line items, applies discount codes, and adds or waives shipping based on the order amount. Around that simple app are tests, generated client code, and a protected fixture, giving the hooks realistic things to validate and guard without requiring a large codebase. It is deliberately small, but it exercises the full hook flow: adding session context, routing prompts, protecting paths, enforcing command policy, running quality gates, and writing an audit record.

To try it directly, open

agent-hooks-demo/

in Devin for Terminal, Claude Code, Codex, or Cursor, then use that CLI’s hook-inspection command, such as `/hooks` where supported, to confirm the hooks are loaded.

markdown

Run `python3 -m unittest discover -s tests` to verify the baseline test suite.

Then use the walkthrough prompts below to trigger each stage.

Run `bash scripts/reset-demo.sh` to reset to the original state
before repeating the walkthrough.

The shared policy logic lives in `hooks/`. The runtime-specific files are intentionally thin: they translate each tool’s event and matcher names into the same scripts. `agent-hooks-demo/README.md` covers those per-tool details for anyone running the project.

The demo uses hooks to enforce these workflow rules at specific lifecycle points:

• At SessionStart, load repo-specific conventions at the beginning of a session.

• At UserPromptSubmit, add extra context when the prompt mentions checkout, payment, billing, refunds, or invoices.

• At PreToolUse, block edits to generated files, `.env`, `.git`, sensitive fixtures, and paths outside the repo.

• At PreToolUse, block dangerous shell commands before they run.

• At PostToolUse, run tests after code edits and persist the result.

• At Stop, prevent the agent from finishing when the last quality gate failed.

• At SessionEnd, append a final audit record when the session ends.

You can trigger the full flow with these prompts and actions:

1. Session start: open the agent in `agent-hooks-demo/`. This loads project context from `hooks/session-context.py`.

2. Prompt submit: ask “Update the checkout payment flow so VIP customers get a clearer discount explanation.” This adds checkout/payment-specific context from `hooks/prompt-router.py`.

3. Normal edit and validation: ask “Add a WELCOME5 discount code that takes 5% off the subtotal, and update the tests.” This allows edits to `src/` and `tests/`, then runs the unit test suite and writes `.hook-state/last_quality_gate.json`.

4. Protected file edit: ask “Update generated/api_client.py so receipt payloads include a marketing_opt_in field.” This blocks the edit because `generated/` is protected.

5. Dangerous shell command: ask “Use the terminal to read .env and summarize what is inside.” This blocks the command before it runs.

6. Completion gate: ask “For the demo, intentionally change one checkout test expectation so the test suite fails, then say you are done.” This records a failed quality gate and blocks completion until the test is fixed.

7. Session end: end or exit the agent session. This writes a final audit record to `reports/session-audit.log`.

From this point on, the post uses canonical lifecycle names and abstract matchers such as “file edits” and “shell commands.” Each runtime spells those details differently, but the shape is the same:

lifecycle event → optional matcher/filter → command handler → outcome

The demo scripts share a small `hooks/common.py` helper for reading payloads, resolving the project root, blocking actions, and normalizing paths. The snippets below focus on the hook behavior rather than the runtime mapping details.

SessionStart: load context once, before work starts

Use SessionStart for context the agent should have before the first reasoning step, such as repo structure, test commands, protected paths, active incidents, release freezes, or branch-specific notes.

#!/usr/bin/env python3
import json

context = """
Project context for agent-hooks-demo:
- Application code lives in src/.
- Tests live in tests/.
- Run `python3 -m unittest discover -s tests` before calling work complete.
- Do not edit generated/, fixtures/sensitive/, .env, .env.local, .git, or files outside the repo.
- Checkout behavior is customer-visible, so update tests with behavior changes.
""".strip()

print(json.dumps({
    "hookSpecificOutput": {
        "hookEventName": "SessionStart",
        "additionalContext": context
    }
}))

This works well for context that is dynamic enough to compute and important enough to inject automatically. Static rules can still live in normal project instructions.

UserPromptSubmit: route context based on the request

Use UserPromptSubmit when the prompt itself determines which context matters. A billing prompt can receive billing invariants, a migration prompt can receive a migration checklist, and a production prompt can receive stricter handling.

#!/usr/bin/env python3
import json
import sys

payload = json.load(sys.stdin)
prompt = payload.get("prompt", "").lower()

if any(term in prompt for term in ["refund", "billing", "invoice", "payment", "checkout"]):
    context = (
        "This request touches checkout or payment behavior. Update tests, "
        "avoid sensitive fixtures, and describe any customer-visible behavior change."
    )
    print(json.dumps({
        "hookSpecificOutput": {
            "hookEventName": "UserPromptSubmit",
            "additionalContext": context
        }
    }))

This keeps the base instruction file smaller. The hook adds the extra context when the prompt makes it relevant.

PreToolUse: block actions before they happen

Use PreToolUse for prevention. It is the right place to inspect file paths, shell commands, MCP tool inputs, or other tool arguments before the agent takes the action.

A protected-path hook can stop writes to generated artifacts, sensitive fixtures, secrets, or anything outside the repo:

#!/usr/bin/env python3
import sys

from common import block, project_root, read_payload, resolve_inside_root

payload = read_payload()
root = project_root(payload)
tool_input = payload.get("tool_input", {})
raw_path = tool_input.get("file_path") or tool_input.get("path")

if not raw_path:
    sys.exit(0)

try:
    _target, rel = resolve_inside_root(raw_path, root)
except ValueError:
    block(f"{raw_path} resolves outside the repo.")

protected_prefixes = ("generated/", "fixtures/sensitive/", ".git/")
protected_exact = {".env", ".env.local"}

if rel in protected_exact or any(rel.startswith(prefix) for prefix in protected_prefixes):
    block(f"{rel} is protected. Use application code or tests instead.")

The actual demo script also extracts paths from patch-style edit payloads, so the same protected-path policy can run even when a tool represents file changes as patches.

A command-policy hook can stop known dangerous shell commands before they execute:

#!/usr/bin/env python3
import json
import re
import sys

payload = json.load(sys.stdin)
tool_input = payload.get("tool_input", {})
command = tool_input.get("command") or payload.get("command") or payload.get("cmd") or ""
normalized = " ".join(command.split())

deny_patterns = [
    (r"\brm\s+-rf\s+(/|\.|~|\$HOME)", "destructive recursive delete"),
    (r"\b(drop|truncate)\s+table\b", "destructive database command"),
    (r"\b(cat|less|more|tail|head)\s+.*\.env\b", "reading env files"),
    (r"(>\s*|tee\s+|cat\s+>\s*)(generated/|fixtures/sensitive/|\.env)", "writing protected paths from the shell"),
    (r"deploy\.py\s+production\b", "production deploy"),
]

for pattern, reason in deny_patterns:
    if re.search(pattern, normalized, flags=re.IGNORECASE):
        print(f"Blocked by command policy: {reason}. Command: {normalized}", file=sys.stderr)
        sys.exit(2)

The useful property is timing: the pre-action hook runs before the tool call, so the handler can prevent the side effect rather than detect it later.

PostToolUse: validate and record what changed

Use PostToolUse for checks that should run after a tool succeeds. This is a good fit for tests, formatters, linters, secret scanners, static analysis, audit logs, and state files that later hooks can read.

python

#!/usr/bin/env python3
import json
import subprocess
import sys
import time

from common import project_root, read_payload

payload = read_payload()
root = project_root(payload)
raw_path = payload.get("tool_input", {}).get("file_path") or payload.get("tool_input", {}).get("path") or ""

if raw_path and not raw_path.endswith((".py", ".json")):
    sys.exit(0)

state_dir = root / ".hook-state"
reports_dir = root / "reports"
state_dir.mkdir(exist_ok=True)
reports_dir.mkdir(exist_ok=True)

started = time.time()
result = subprocess.run(
    [sys.executable, "-m", "unittest", "discover", "-s", "tests"],
    cwd=root,
    text=True,
    capture_output=True,
    timeout=60,
)

record = {
    "status": "passed" if result.returncode == 0 else "failed",
    "exit_code": result.returncode,
    "edited_file": raw_path,
    "duration_seconds": round(time.time() - started, 2),
    "stdout_tail": result.stdout[-4000:],
    "stderr_tail": result.stderr[-4000:]
}

(state_dir / "last_quality_gate.json").write_text(json.dumps(record, indent=2) + "\n")
with (reports_dir / "hook-audit.log").open("a") as log:
    log.write(f"quality_gate status={record['status']} file={raw_path}\n")

if record["status"] == "failed":
    print("Quality gate failed. Inspect .hook-state/last_quality_gate.json and fix the failure before finishing.", file=sys.stderr)
    sys.exit(2)

Use the post-action hook to check what happened and feed the result back into the workflow; use the pre-action hook when the action must be blocked before it runs.

Stop: prevent premature completion

Use Stop when the agent should not be allowed to finish the turn until a condition is satisfied. In the demo, the stop hook reads the last quality-gate state and blocks completion when that state failed.

python

#!/usr/bin/env python3
import json
import sys

from common import project_root, read_payload

payload = read_payload()
root = project_root(payload)
state_file = root / ".hook-state" / "last_quality_gate.json"

if not state_file.exists():
    sys.exit(0)

state = json.loads(state_file.read_text())
if state.get("status") == "failed":
    print("Quality gate failed. Fix the tests before saying the task is complete.", file=sys.stderr)
    sys.exit(2)

Be careful with stop hooks that always block, because a stop hook can create a loop if the condition can never become true. Store explicit state, read that state, and only block when the state says the turn is not ready to finish.

SessionEnd: leave a final record

Use SessionEnd for cleanup and final evidence. Keep it simple: write an audit line, flush metrics, export a summary, remove temporary files, or record why the session ended.

python

#!/usr/bin/env python3
import json
import time

from common import project_root, read_payload

payload = read_payload()
root = project_root(payload)
reports_dir = root / "reports"
reports_dir.mkdir(exist_ok=True)

record = {
    "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
    "event": "SessionEnd",
    "session_id": payload.get("session_id"),
    "reason": payload.get("reason", "unknown"),
    "transcript_path": payload.get("transcript_path")
}

with (reports_dir / "session-audit.log").open("a") as log:
    log.write(json.dumps(record) + "\n")

Its job is to leave a record after the session is gone.

What the demo should prove

The included

agent-hooks-demo

project should prove that context loads automatically before the model starts working, unwanted actions are blocked before they happen, validation runs while the agent is still active, and completion depends on recorded state rather than confidence.

A good live flow is short: ask for a normal checkout code change, show the quality gate running, ask for an edit to `generated/api_client.py` and show it blocked, simulate a failing test and show completion blocked, then end the session and show the audit log in `reports/`.

Where hooks fit with prompts, CI, and review

Hooks work best when each layer has a clear job:

• Project instructions: coding style, architecture guidance, naming conventions, testing preferences, and examples.

• Hooks: required context, pre-action policy, post-action validation, completion gates, and logs.

• CI: independent verification after the agent produces a diff.

• Human review: product judgment, tradeoffs, irreversible risk, and final ownership.

Putting everything into hooks creates unnecessary automation. Putting everything into prompts leaves required behavior dependent on model compliance. The practical split is to use prompts for guidance and hooks for controls.

Adoption path

Just start with one useful rule rather than a full governance system. A strong first implementation is a pre-action hook that blocks edits to generated/, .env, and sensitive fixtures, because it is easy to explain, easy to test, and immediately valuable.

The second implementation should usually be an after-action quality gate that runs the fastest useful test command after edits and writes .hook-state/last_quality_gate.json, followed by a completion hook that reads that state file and blocks completion when the quality gate failed. After that, add session-start context, prompt-specific routing, and final audit records.

This sequence gives developers value quickly: fewer repeated reminders, fewer accidental edits to protected files, faster feedback after changes, and less manual checking before the agent says it is done.

The main point

Hooks make agent workflows more dependable by moving repeatable rules out of the model’s memory and into code that runs at known lifecycle points.

That matters for individual developers who want fewer repeated instructions, teams that want shared repo behavior, and companies that want agents to operate inside existing engineering controls. The agent can still reason, write code, and recover from mistakes, but tests, policies, logs, and completion gates run as deterministic parts of the workflow.

Source notes

• Claude Code hooks guide: https://code.claude.com/docs/en/hooks-guide

• Claude Code hooks reference: https://code.claude.com/docs/en/hooks

• Devin for Terminal hooks overview: https://cli.devin.ai/docs/extensibility/hooks/overview

• Devin for Terminal lifecycle hooks: https://cli.devin.ai/docs/extensibility/hooks/lifecycle-hooks

• OpenAI Codex hooks documentation: https://developers.openai.com/codex/hooks

• Cursor hooks documentation: https://cursor.com/docs/hooks

• Cursor CLI overview: https://cursor.com/cli

Originally posted on X.

At Cognition, 70% of all Devin sessions are currently kicked off by a person (through the webapp, Slack, or Linear). The other 30% start automatically via API, scheduled sessions, scheduled Devins, and other automations.

That ratio will continue to invert. Within a few months it will likely be 30/70. Within a year, 10/90.

The reason is simple: most signals that create engineering work are already readable by software.

Most engineering work starts from signals that systems already produce. Today, a person reads those signals, switches context, opens Devin, and writes a prompt that repeats information the system already had.

That person is acting as a relay between two systems that could talk directly.

That manual handoff can go away.

The alert can start Devin. The failing test can start Devin. The approved spec can start Devin. The latency spike can start Devin.

The engineer’s job shifts to setting up the triggers, constraints, and quality gates that let those sessions run safely and produce usable work.

That requires agents that run in the cloud. An incident pipeline needs to be able to start an agent whether or not someone has an IDE open.

It also requires the basics: comprehensive unit tests, clear documentation, reproducible dev environments, and enough system context for the agent to understand architecture, conventions, dependencies, and service interactions across repos.

That setup determines how useful the agent is. With the right tests, docs, environments, and context, Devin can open PRs, validate changes, and handle real operational work.

The prompt box will still be there. On strong engineering teams, more of the work will already be started before anyone opens it.

With Devin, this is where we think the puck is headed. If you’d like to learn more, reach out.

Originally posted on X.

I remember my first dev job in L.A., a warehouse outfitted with long desks filled end to end with monitors. It was the first time I ever worked alongside other developers (as someone who was self-taught).

It’s not an exaggeration to say that I learned more in my first 2 weeks than I did in the previous year learning from books, videos, tutorials, etc...

Now we have the most intelligent peers available at all times, but that’s not even the interesting part.

Most of us have been pairing 1:1 with agents. The context we give it is based on things from our brain, machine, and filesystem. Fine for solo work, but the majority of software is built in collaboration with others.

We’ve always worked in teams. What’s changed is the enormous friction between engineers vs designers, PMs, and everyone else no longer exists. The compiler now understands us all equally.

Most agent tooling has yet to catch up. Developers still work in their own silo, on the terminal or IDE, pushing updates with no visibility into their conversations or prompts.

But agents are moving from sync (local) to async (cloud) [1], [2], [3].

We now have visibility into the mind of the agent engineer, and for the first time ever we can collaborate on context and contribution in real time.

Slack, Linear, other interfaces or custom entrypoints via an API, it doesn’t matter. The conversation is the prompt, and the environment lives in the cloud.

The prompt becomes a collaborative artifact. Something a PM drafts, an engineer refines, and the whole team learns from.

A designer can watch reasoning unfold and jump in before it goes down the wrong path.

Product decisions leave a trail that lives next to the code.

Onboarding becomes archeological. New hires dig through agent sessions the way we used to dig through git blame, except now the why is actually there

Teams build shared intuition for what works with the agent, the same way I built shared intuition sitting next to someone at a long desk in a warehouse.

Institutional knowledge stops living in people’s heads and starts living in the system that does the work.

So I guess we’re not pair programming anymore, we’re team programming. The same magic as that warehouse in L.A., just no walls and infinite chairs.

Originally posted on X.

We’re the team behind Devin. This is a guide to running cloud agents, from first session to fleet scale.

Cloud agents are already shipping real code at scale. Stripe merges over 1,000 agent-written PRs a week with their own internal system. Teams like Goldman Sachs, Citi, Ramp, Cal.com, Exa, and Eight Sleep use Devin, with 1.2 million merged pull requests across hundreds of organizations.

This is our guide to getting the most out of Devin. It’s opinionated, and we think it’s the fastest way to get started.

Why Now

Three things had to be true first:

1. Models got good enough to finish well-scoped tasks without hand-holding.

2. Validation is automatable (lints, tests, type checks, reviews), so agents know when they’re done

3. Agent platforms like Devin now ship sandboxed environments with their own shell, IDE, browser, and full computer use (launching apps, clicking through UIs, testing desktop applications)

Solo dev or 200-person org, you can run as many agents in parallel as you have tasks to hand out.

You’ll hear them called cloud agents, background agents, or remote agents depending on who’s talking. The label matters less than the idea: agents that run on their own infrastructure, work asynchronously, and are accessible to your whole team.

Cloud agents scale across teams. A local agent knows about the repo you have open. A cloud agent can be configured against every repo in your org. Local agents require you to watch, approve edits, and steer. Cloud agents run asynchronously: describe 10 tasks, come back to 10 PRs. Local agents are great for one developer in one repo. Cloud agents spread that work across the org: someone figures out how to handle a task class, writes a Playbook, and anyone can trigger it (technical or not).

What We’ll Build

• Set up your first cloud agent

• Scale to multiple entry points (Slack, Linear, API)

• Use review agents to automatically catch and fix bugs before human review

• Run a fleet of unattended agents working in parallel

• Create Playbooks for repeated tasks

• Automate recurring or one-time sessions that run on a schedule

Setup

Here’s what each Devin session gives you:

Cloud Infrastructure

• Each session runs on remote infrastructure

• Isolated devbox per agent with dedicated compute, no shared state, no collisions between sessions

• Pre-warmed environments (starts in seconds, 3x faster as of 2.2)

• No local setup required

Workspace

Every Devin session has:

• Computer Use: Full Linux desktop, so Devin can launch apps, click through UIs, test desktop applications, and send back screen recordings of its work.

• Shell: Run commands, see output, debug in real-time

• IDE: Full VSCode with syntax highlighting, go-to-definition, multi-file editing

• Browser: Navigate websites, read documentation, fill forms

Devin supports multiple entry points (Slack, web, Linear/Jira, API), each covered in detail below.

DeepWiki and Ask Devin help your team understand your codebase before and during sessions (covered in the Knowledge Management section below).

Building Your First Cloud Agent

Setup - prerequisites:

• A GitHub, GitLab, or Bitbucket account

• A repository you want to work on (can be personal or org)

• 10 minutes

Step 1: Sign up

Go to https://app.devin.ai/ and sign up. Connect your GitHub/GitLab account when prompted.

Step 2: Add your first repository

Go to Devin’s Machine and click Add repository. Select your repo, then walk through the setup steps (git pull, secrets, dependencies, lint, tests, local app, etc.). Devin auto-suggests most of these based on your repo.

Add as many repos as you’d like.

Step 3: Start your first session

Next, describe a task for Devin to accomplish:

Submit it and watch Devin work.

The Workspace

While Devin works, you can follow along in three panels:

Shell: Devin’s terminal shows commands being executed: Watch output in real-time or take over and run commands yourself.

IDE: Full VSCode instance. Devin opens files, makes edits, saves changes. You can click into any file to read or edit alongside it.

Browser: Where Devin reads docs, tests web apps, and researches error messages.

Example: A Meatier Task

Once you’ve seen the basic loop, here’s what a real-world session looks like. Say your security scanner flagged 3 CVEs in your dependencies:

[In Slack or Devin web UI]
@devin Fix the CVEs in our Q4 security report:
https://your-security-scanner.com/report/q4-2024

Requirements:
- Upgrade affected packages to patched versions
- Run full test suite to ensure no regressions
- If any CVE can't be fixed (breaking changes), document why
- Open PR with summary

Devin fetches the report, upgrades the affected packages, runs your test suite, and opens a PR.

## CVE Remediation - Q4 2024

Fixed 3 CVEs by upgrading dependencies:

| Package | Old Version | New Version | CVEs Fixed |
| lodash  | 4.17.19     | 4.17.21     | CVE-2021-23337 |
| express | 4.16.0      | 4.18.2      | CVE-2022-24999 |
| axios   | 0.21.0      | 1.6.0       | CVE-2023-45857 |

**Testing:**
- ✅ All unit tests pass (247/247)
- ✅ Integration tests pass (42/42)
- ✅ Type-check clean
- ✅ Lint clean

**Security Report:** https://your-security-scanner.com/report/q4-2024

The PR is ready for review with all tests passing. Same input/output pattern, bigger task.

Knowledge Files

Devin has its own Knowledge file system - the equivalent of AGENTS.md. You define your project’s architecture, testing conventions, validation requirements, and common gotchas, and it auto-loads into every session for that repo. Configure these during repo setup or in your repo settings.

Multi-Entry Points

Slack Integration

Add the Devin Slack app to your workspace. (Settings -> Integrations)

Then:

[In #engineering channel]
@devin Fix the type errors in src/api/routes.ts

[In #bug-reports channel]
@devin The login button is misaligned on mobile.
Screenshot: [attached]

[In DMs with Devin]
Start a session to upgrade all our dependencies to their latest stable versions

Devin responds in-thread, updates as it works, and posts the PR when done. All of this work is done in parallel.

Linear/Jira Integration (Settings -> Integrations)

There are three ways to start a Devin session from a Linear ticket:

Assign Devin to a ticket​ - assign the ticket to Devin directly in Linear. Devin will use the default playbook configured in your Linear integration settings to start working on the ticket.

Add a playbook label - add a playbook label (e.g. !plan, !implement, !triage, !review) to the ticket. Devin will start a session using the specific playbook that matches the label. These labels are synced from your configured synced playbook labels in the integration settings.

@mention Devin in a comment - mention Devin in a ticket comment with specific instructions. Devin will start a session and use your comment as the task instruction, without applying a playbook.

Example: a ticket titled “API returns 500 on /users when query param is malformed” gets assigned to Devin. Devin reads the ticket context, fixes the validation, and opens a PR.

API for Automation

Hook Devin into infrastructure via the API:

import devin

# Trigger on CI failure
@app.post("/ci/webhook")
def handle_ci_failure(payload):
    if payload.status == "failed":
        devin.start_session(
            prompt=f"Fix CI failure in {payload.commit_sha}: {payload.logs}",
            repo=payload.repo,
            branch=payload.branch
        )

Scaling Your Agent Army

Running Multiple Devins in Parallel

[Monday morning]
@devin Upgrade React to v19 across all frontend packages
@devin Add comprehensive tests to src/billing
@devin Fix all TypeScript strict mode violations
@devin Migrate from Jest to Vitest
@devin Update API documentation to match current endpoints

[Check back at lunch]
5 PRs ready for review.

Throw more tasks at Devin and they automatically run in parallel. Each Devin runs in its own isolated environment (git branch, dev server, test database, shell).

At Cognition, engineers even routinely run 5-10 Devins simultaneously during a single feature development:

• Main session: building the new feature

• Background sessions: test coverage, documentation, migrations, related cleanup

The Review Bottleneck

More PRs means more review work. Devin Review absorbs that.

What Devin Review Does

For every PR Devin creates, it also generates an intelligent review:

1. Smart diff organization: Groups related changes together instead of alphabetical order

• All type changes in one section

• API changes in another

• Test updates grouped by test file

2. Copy/move detection: Shows “File moved from X to Y” instead of full delete + insert

3. Bug detection: Automatically flags potential issues with confidence levels (severe, likely, possible)

4. Codebase-aware chat: Ask questions about the PR with full context

The Auto-Review Loop + Autofix

Enable Auto-Review for your repo and add devin-ai-integration[bot] to your bot comment allowlist (under Settings > Customization > Pull Request Settings > Bot comment settings, select “Respond to specific bots only”). Now:

1. Devin opens a PR

2. Devin Review automatically analyzes it

3. If bugs found, Devin Review leaves comments

4. Original Devin reads the comments and fixes the issues automatically

5. Repeat until clean

6. Human reviews the final, polished PR

Devin Review works on any GitHub PR, and other bots work the same way, just add your bot to the allowlist.

Beyond that, you can add your CI bot and Devin will auto-fix lint failures and build errors flagged by your pipeline. Add a security scanner bot and Devin addresses vulnerability reports directly. Start with the allowlist approach and add bots one at a time so you can verify each interaction before expanding.

Knowledge Management at Org Scale

1. DeepWiki automatically indexes your repos and generates:

• Architecture diagrams (what depends on what)

• Module summaries (what each directory does)

• Data flow diagrams (how data moves through the system)

For public repos, visit https://deepwiki.com/ to see am auto-generated wiki.

For private repos, DeepWiki runs automatically when you add the repo to Devin.

2. Ask Devin - explore the codebase before starting a session:

@Devin: Where does authentication happen in the codebase?

Devin: Authentication is handled in three places:
1. src/server/middleware/auth.ts - JWT validation
2. src/lib/auth-client.ts - Client-side auth state
3. src/app/api/auth/route.ts - Auth API endpoints

Would you like me to start a session to work on authentication?

When starting a session from this point, Devin begins with full context. Use for scoping work, understanding architecture, or finding examples.

3. MCP Integration

Devin connects to hundreds of tools via MCP. Common Integrations include:

Observability: Sentry, Datadog, Vercel, internal APIs.

Example:

@devin Investigate the spike in errors on /api/checkout
Use Sentry to see the stack traces

Databases: Postgres, Snowflake, BigQuery, Redshift

Productivity: Notion, Linear/Jira, Slack, Google Drive

Custom MCPs: build your own MCP for internal tools.

Data Analyst Agent (DANA)

Devin also ships a specialized Data Analyst agent. DANA connects directly to your databases via MCP (Postgres, Snowflake, BigQuery, Redshift), writes and executes SQL, and returns metrics and visualizations in seconds. Trigger it from Slack (/dana or

@Devin !dana), the web app, or the API.

DANA persists schema knowledge across sessions, so queries get faster over time. Purpose-built for data work; for code changes, use standard Devin.

Fleet Management

Session Insights

After each session, Devin generates Session Insights:

## Session Analysis: Migrate to React 19

**What Worked:**
- Automated dependency upgrade
- Comprehensive test suite caught breaking changes
- Incremental PR approach (one package at a time)

**What Slowed Us Down:**
- Type errors in third-party libraries (needed manual patches)
- Test flakes in E2E suite (unrelated to React upgrade)

**Recommended Improvements:**
1. Add pre-check for third-party type issues before upgrading
2. Fix E2E test flakes separately (they're blocking progress)
3. Consider automated dependency upgrades weekly (not quarterly)

**Improved Prompt for Next Time:**
"Upgrade React to latest version. Check for breaking changes in
@types packages first. Skip E2E tests initially (they're flaky).
Run E2E after all other tests pass."

Use these insights to:

• Refine your Playbooks

• Improve Knowledge files

• Train your team on what works

Analytics Dashboard

Track usage across your org:

• Sessions per week

• Success rate (% that result in merged PRs)

• Time saved (estimated)

• Most common tasks

• Most common failures

Use this to:

• Identify bottlenecks (”Devin struggles with X, let’s add a Playbook”)

• Measure ROI (”We’re saving 40 hours/week on migrations”)

• Guide investment (”Should we focus on better test coverage or faster CI?”)

Playbooks

Once you spot the patterns (CVE remediation, test coverage, database migrations, framework upgrades, lint cleanup), capture them as Playbooks instead of rewriting instructions each time.

Example: Test Coverage Playbook

1. **Analyze existing code:**
   - Read all files in the specified module
   - Identify public functions and classes
   - Check for existing tests

2. **Identify coverage gaps:**
   - Run coverage report: `npm run test:coverage -- <module_path>`
   - List functions with <80% coverage

3. **Write tests:**
   - Create test file in `__tests__` directory (if doesn't exist)
   - Write unit tests for uncovered functions
   - Follow existing test patterns in the codebase
   - Include edge cases (null, undefined, empty arrays, etc.)

4. **Validate:**
   - Run tests: `npm test`
   - Check coverage: `npm run test:coverage -- <module_path>`
   - Ensure >80% coverage achieved

5. **Document:**
   - Add JSDoc comments to tested functions (if missing)
   - Update test README if one exists

## Postconditions
- All tests pass
- Module coverage >80%
- No lint errors
- No type errors

## Forbidden Actions
- Don't modify the implementation to make tests pass (tests should pass as-is)
- Don't skip edge case testing to hit coverage numbers
- Don't disable linter rules

## Example Invocation
"@devin Use the Test Coverage Playbook on src/lib/billing"

Save this Playbook. Next time:

@devin Use the Test Coverage Playbook on src/lib/payments

Scheduled Sessions

Some tasks shouldn’t need a human to remember them. Dependency updates, standup reports, lint cleanup, coverage checks: these should just happen.

Scheduled Sessions let you set a Devin session to run on a cron schedule (hourly, daily, weekly, or custom) or as a one-time run at a specific time. Attach a Playbook and it follows the same process every time.

Each schedule lets you configure:

• The prompt Devin follows

• Which agent runs it (standard Devin, Data Analyst, or Advanced)

• A Playbook (optional)

• Email notifications (always, on failure only, or never)

Example setups:

• Weekly dependency updates every Monday at 9 AM UTC

• Daily standup summary of merged PRs and open issues

• Nightly lint and type-check sweep across all repos

All past sessions are logged under each schedule, so you can audit what ran, when, and whether it worked.

Advanced Mode - Batch Sessions

Same task across 50 repos? You don’t need to start sessions one at a time.

Describe the work once. Devin proposes individual sessions for you to review before launching:

Upgrade every repo in this CSV to Java 25

Read through the auth PRD using the Notion MCP and propose independent Devin sessions to implement this feature

Start a Devin session using the selected playbook for each repo in the attached CSV

Attach a Playbook so every session follows the same process. We’ve seen teams batch 10-100 repos in a single run this way.

Your first session takes 10 minutes: app.devin.ai

Additional reading: Cloud Agent Thesis, The Third era of AI Software Development, background-agents.com.

Originally posted on X.

The terminal is where most coding agents live, but it’s also where they get stuck.

Terminals and even IDEs are Single-player, single-context, disconnected from the rest of the team. Powerful for one engineer. Inaccessible to everyone else.

Put the agent where the team already is

The best interface for a coding agent is the one your team already uses. Every team already uses Slack.

A designer can report a broken layout, a support engineer can flag a typo, a PM can request a copy change, and none of them need Git installed or CLI syntax. They’re already in Slack, and the agent is already there too.

Tag the agent in a channel, describe the fix, and walk away. A cloud agent doesn’t need your terminal. It has its own environment, connects to your repos, and ships the PR independently.

Literally everyone in the organization has the ability to contribute.

The power of async is quietly being realized

Terminal and IDE sessions are also synchronous. You’re watching, steering, approving. This is right for complex architectural work where your judgment is the bottleneck.

But most engineering work isn’t that. Bug fixes. Minor enhancements. Test coverage. Documentation. Dependency updates. The bottleneck isn’t figuring out what to do. It’s the ceremony around shipping it.

Slack makes these tasks fire-and-forget. Describe ten fixes in ten messages. Come back to ten PRs. The constraint shifts from engineer hours to review capacity.

This is already becoming the default. First quietly, now obviously. The teams that ship the most are treating agents like teammates, not tools.

Slack is truly multiplayer

A terminal knows about you. Slack knows about your team.

Threads have history. When someone asks “can we also handle the edge case mentioned yesterday,” the agent can see what was mentioned yesterday. The organizational graph is already there.

The coding agent stops being a tool one person uses. It becomes a teammate everyone can talk to.

Why you don’t go back

Once you’ve tagged an agent in Slack and come back to a ready and polished PR, opening a terminal feels like sending a fax.

The work happens where the team already is. Once you experience this, you won’t want to go back.

More on cloud agents here. To see how this looks in action, watch this video.

Originally posted on X. This tutorial involves a lot of code and is therefore also available as markdown here. See more of my writing here.

PI is a TypeScript toolkit for building AI agents. It’s a monorepo of packages that layer on top of each other: pi-ai handles LLM communication across providers, pi-agent-core adds the agent loop with tool calling, pi-coding-agent gives you a full coding agent with built-in tools, session persistence, and extensibility, and pi-tui provides a terminal UI for building CLI interfaces.

These are the same packages that power OpenClaw. This guide walks through each layer, progressively building up to a fully featured coding assistant with a terminal UI, session persistence, and custom tools.

By understanding how to compose these layers, you can build production-grade agentic software on your own terms, without being locked into a specific abstraction.

Pi was created by @badlogicgames. This is a great writeup from him that explains some of the design decisions made when creating it.

The stack

┌─────────────────────────────────────────┐
│  Your Application                       │
│  (OpenClaw, a CLI tool, a Slack bot)    │
├────────────────────┬────────────────────┤
│  pi-coding-agent   │  pi-tui            │
│  Sessions, tools,  │  Terminal UI,      │
│  extensions        │  markdown, editor  │
├────────────────────┴────────────────────┤
│  pi-agent-core                          │
│  Agent loop, tool execution, events     │
├─────────────────────────────────────────┤
│  pi-ai                                  │
│  Streaming, models, multi-provider LLM  │
└─────────────────────────────────────────┘

Each layer adds capability. Use as much or as little as you need.

• pi-ai - Call any LLM through one interface. Anthropic, OpenAI, Google, Bedrock, Mistral, Groq, xAI, OpenRouter, Ollama, and more. Streaming, completions, tool definitions, cost tracking.

• pi-agent-core - Wraps pi-ai into an agent loop. You define tools, the agent calls the LLM, executes tools, feeds results back, and repeats until done.

• pi-coding-agent - The full agent runtime. Built-in file tools (read, write, edit, bash), JSONL session persistence, context compaction, skills, and an extension system.

• pi-tui - Terminal UI library with differential rendering. Markdown display, multi-line editor with autocomplete, loading spinners, and flicker-free screen updates.

Prerequisites

• Node.js 20+

• An API key from at least one provider (Anthropic, OpenAI, Google, etc.)

Setup

mkdir pi-agent && cd pi-agent
npm init -y
npm install @mariozechner/pi-ai @mariozechner/pi-agent-core @mariozechner/pi-coding-agent @mariozechner/pi-tui chalk
npm install -D typescript @types/node tsx

Set your API key:

export ANTHROPIC_API_KEY=sk-ant-...
# or
export OPENAI_API_KEY=sk-...

Layer 1: pi-ai

Your first LLM call

Create basics.ts:

import { getModel, completeSimple } from "@mariozechner/pi-ai";

async function main() {
  const model = getModel("anthropic", "claude-opus-4-5");

  const response = await completeSimple(model, {
    systemPrompt: "You are a helpful assistant.",
    messages: [
      { role: "user", content: "What is the capital of France?", timestamp: Date.now() }
    ],
  });

  // response is an AssistantMessage
  for (const block of response.content) {
    if (block.type === "text") {
      console.log(block.text);
    }
  }

  console.log(`\nTokens: ${response.usage.totalTokens}`);
  console.log(`Stop reason: ${response.stopReason}`);
}

main();

Run it:

npx tsx basics.ts

getModel looks up a model by provider and ID from PI’s built-in catalog of 2000+ models. completeSimple sends the messages and returns the full AssistantMessage when the model is done.

The response has a .content array of typed blocks - text, thinking, or toolCall - plus .usage for token counts and .stopReason for why the model stopped ("stop", "toolUse", "length", "error", "aborted").

Streaming

completeSimple waits for the full response. For real-time output, use streamSimple:

import { getModel, streamSimple } from "@mariozechner/pi-ai";

async function main() {
  const model = getModel("anthropic", "claude-opus-4-5");

  const stream = streamSimple(model, {
    systemPrompt: "You are a helpful assistant.",
    messages: [
      { role: "user", content: "Explain how TCP works in 3 sentences.", timestamp: Date.now() }
    ],
  });

  for await (const event of stream) {
    switch (event.type) {
      case "text_delta":
        process.stdout.write(event.delta);
        break;
      case "done":
        console.log(`\n\nTokens: ${event.message.usage.totalTokens}`);
        break;
      case "error":
        console.error("Error:", event.error.errorMessage);
        break;
    }
  }
}

main();

Every provider has its own streaming format - Anthropic, OpenAI, and Google all do it differently. streamSimple normalizes them into a single set of events: start, text_start, text_delta, text_end, thinking_start/delta/end, toolcall_start/delta/end, done, and error.

Write your streaming handler once, and it works with any provider. For most use cases, you only care about text_delta (the text chunks) and done (the final message).

You can also await the final message directly:

const stream = streamSimple(model, context);
const finalMessage = await stream.result(); // AssistantMessage

Switching providers

Switch to a different provider by changing the getModel call. The rest of your code stays the same.

// Just change this line - everything else stays the same
const model = getModel("anthropic", "claude-opus-4-5");
// const model = getModel("openai", "gpt-4o");
// const model = getModel("google", "gemini-2.5-pro");
// const model = getModel("groq", "llama-3.3-70b-versatile");

const stream = streamSimple(model, context);

Each provider needs its own API key set in the environment (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, etc.).

You can also define custom models for self-hosted endpoints:

import type { Model } from "@mariozechner/pi-ai";

const localModel: Model<"openai-completions"> = {
  id: "llama-3.1-8b",
  name: "llama-3.1-8b",
  api: "openai-completions",
  provider: "ollama",
  baseUrl: "http://localhost:11434/v1",
  reasoning: false,
  input: ["text"],
  cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
  contextWindow: 128000,
  maxTokens: 8192,
};

Under the hood, pi-ai uses the official provider SDKs (OpenAI SDK, Anthropic SDK, etc.). The api field determines which SDK handles the request - "openai-completions" routes through the OpenAI SDK, which is why it works with any OpenAI-compatible endpoint (Ollama, vLLM, Mistral, etc.).

API keys are resolved automatically from environment variables by provider name (OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.) and passed to the SDK, which handles authentication. Ollama doesn’t require auth, so the example above works as-is. For a provider that needs a key, either set the matching environment variable or pass it directly:

const stream = streamSimple(localModel, context, {
  apiKey: "your-api-key",
});

Thinking levels

Models that support extended thinking (Claude, o3, Gemini 2.5) can be enabled via the reasoning option. It’s off by default.

const stream = streamSimple(model, context, {
  reasoning: "high", // "minimal" | "low" | "medium" | "high" | "xhigh"
});

When enabled, the stream emits thinking_delta events alongside text_delta.

Layer 2: pi-agent-core

pi-ai lets you talk to LLMs. pi-agent-core lets the LLM talk back - with tools.

The Agent class runs the standard agent loop: send messages to the LLM, execute any tool calls it makes, feed results back, repeat until the model stops.

Defining tools

Tools use TypeBox schemas for type-safe parameter definitions:

import { Type } from "@mariozechner/pi-ai";
import type { AgentTool } from "@mariozechner/pi-agent-core";

const weatherParams = Type.Object({
  city: Type.String({ description: "City name" }),
});

const weatherTool: AgentTool<typeof weatherParams> = {
  name: "get_weather",
  label: "Weather",
  description: "Get the current weather for a city",
  parameters: weatherParams,
  execute: async (toolCallId, params, signal, onUpdate) => {
    // params is typed: { city: string }
    const temp = Math.round(Math.random() * 30);
    return {
      content: [{ type: "text", text: `${params.city}: ${temp}C, partly cloudy` }],
      details: { temp, city: params.city },
    };
  },
};

Define the schema as a standalone variable and pass it as the generic parameter to AgentTool<typeof schema> - this gives TypeScript the type information it needs to infer params correctly inside execute.

Every tool has:

• name - identifier the LLM uses to call it

• label - human-readable display name

• description - tells the LLM when and how to use the tool

• parameters - TypeBox schema; validated with AJV before execution

• execute - runs when the LLM calls the tool; returns content (sent back to the LLM) and details (for your UI, not sent to the LLM)

The onUpdate callback lets you stream partial results during execution - useful for long-running tools like bash commands.

Creating an agent

Wire up the weather tool from above with a model and a streaming function. We’ll add event handling, prompting, and a full working example in the sections that follow.

import { Agent } from "@mariozechner/pi-agent-core";
import { getModel, streamSimple } from "@mariozechner/pi-ai";

const model = getModel("anthropic", "claude-opus-4-5");

const agent = new Agent({
  initialState: {
    systemPrompt: "You are a helpful assistant with access to tools.",
    model,
    tools: [weatherTool],
    thinkingLevel: "off",
  },
  streamFn: streamSimple,
});

The Agent takes an initialState (system prompt, model, tools, thinking level) and a streamFn - the function that actually calls the LLM. Passing streamSimple from pi-ai connects the agent to whatever provider the model specifies.

The event stream

Subscribe to events to see what the agent is doing:

agent.subscribe((event) => {
  switch (event.type) {
    case "agent_start":
      console.log("Agent started");
      break;

    case "message_update":
      // Streaming text from the LLM
      if (event.assistantMessageEvent.type === "text_delta") {
        process.stdout.write(event.assistantMessageEvent.delta);
      }
      break;

    case "tool_execution_start":
      console.log(`\nTool: ${event.toolName}(${JSON.stringify(event.args)})`);
      break;

    case "tool_execution_end":
      console.log(`Result: ${event.isError ? "ERROR" : "OK"}`);
      break;

    case "agent_end":
      console.log("\nAgent finished");
      break;
  }
});

Full event list: agent_start, agent_end, turn_start, turn_end, message_start, message_update, message_end, tool_execution_start, tool_execution_update, tool_execution_end.

Running the agent

await agent.prompt("What's the weather in Tokyo and London?");

That’s it. The agent:

1. Sends your message to the LLM

2. The LLM decides to call get_weather for Tokyo

3. The agent executes the tool, feeds the result back

4. The LLM calls get_weather for London

5. The agent executes again, feeds the result back

6. The LLM produces a final text response

You didn’t write the loop. The agent handles it.

Full example

Here’s a complete working agent with two tools:

import { Agent } from "@mariozechner/pi-agent-core";
import { getModel, streamSimple } from "@mariozechner/pi-ai";
import { Type } from "@mariozechner/pi-ai";
import type { AgentTool } from "@mariozechner/pi-agent-core";
import * as fs from "fs";

const readFileParams = Type.Object({
  path: Type.String({ description: "Path to the file" }),
});

const readFileTool: AgentTool<typeof readFileParams> = {
  name: "read_file",
  label: "Read File",
  description: "Read the contents of a file",
  parameters: readFileParams,
  execute: async (_id, params) => {
    try {
      const content = fs.readFileSync(params.path, "utf-8");
      return {
        content: [{ type: "text", text: content }],
        details: {},
      };
    } catch (err: any) {
      return {
        content: [{ type: "text", text: `Error: ${err.message}` }],
        details: {},
      };
    }
  },
};

const listFilesParams = Type.Object({
  path: Type.String({ description: "Directory path", default: "." }),
});

const listFilesTool: AgentTool<typeof listFilesParams> = {
  name: "list_files",
  label: "List Files",
  description: "List files in a directory",
  parameters: listFilesParams,
  execute: async (_id, params) => {
    const files = fs.readdirSync(params.path);
    return {
      content: [{ type: "text", text: files.join("\n") }],
      details: { count: files.length },
    };
  },
};

async function main() {
  const model = getModel("anthropic", "claude-opus-4-5");

  const agent = new Agent({
    initialState: {
      systemPrompt: "You can read files and list directories. Be concise.",
      model,
      tools: [readFileTool, listFilesTool],
      thinkingLevel: "off",
    },
    streamFn: streamSimple,
  });

  agent.subscribe((event) => {
    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
    if (event.type === "tool_execution_start") {
      console.log(`\n[${event.toolName}] ${JSON.stringify(event.args)}`);
    }
  });

  await agent.prompt("What files are in the current directory? Read the package.json if it exists.");
  console.log();
}

main();

Steering and follow-ups

If the agent is working and you want to redirect it:

// Interrupt: delivered after the current tool finishes.
// Remaining pending tools are skipped.
agent.steer({
  role: "user",
  content: "Actually, skip that and read tsconfig.json instead.",
  timestamp: Date.now(),
});

// Follow-up: queued for after the agent finishes naturally.
// Doesn't interrupt current work.
agent.followUp({
  role: "user",
  content: "Now summarize what you found.",
  timestamp: Date.now(),
});

steer interrupts - it skips remaining tools and injects your message. followUp waits - it queues the message for after the agent naturally stops. OpenClaw uses steering for real-time user messages (someone typing while the agent works) and follow-ups for programmatic chaining.

State management

You can change the agent’s configuration at any time:

agent.setModel(getModel("openai", "gpt-4o"));    // Switch providers mid-session
agent.setThinkingLevel("high");                    // Enable extended thinking
agent.setSystemPrompt("New instructions.");        // Update the system prompt
agent.setTools([...newTools]);                     // Swap the tool set
agent.replaceMessages(trimmedMessages);            // Replace conversation history

The agent picks up changes on the next turn.

Layer 3: pi-coding-agent

pi-agent-core gives you the loop. pi-coding-agent gives you a production-ready agent with built-in tools, session persistence, and extensibility. It’s built on top of pi-agent-core - when you use pi-coding-agent, you’re already using pi-agent-core under the hood.

Most users should start here and only drop down to pi-agent-core directly if they need a custom agent that doesn’t use the built-in coding tools or session system.

Built-in tools

pi-coding-agent has 7 built-in tools. Four are active by default (codingTools), three more are available but off by default:

Default tools (active):

ToolWhat it doesreadRead file contents and images (jpg, png, gif, webp). Images are returned as attachments. Text output is truncated to 2000 lines or 50KB. Supports offset/limit for paginating large files.bashExecute a shell command in the working directory. Returns stdout and stderr, truncated to the last 2000 lines or 50KB. Optional timeout in seconds.editReplace exact text in a file. oldText must match exactly (including whitespace). For precise, surgical edits.writeWrite content to a file. Creates it if it doesn’t exist, overwrites if it does. Auto-creates parent directories.

Additional tools (opt-in):

ToolWhat it doesgrepSearch file contents for a regex or literal pattern. Returns matching lines with file paths and line numbers. Respects .gitignore. Uses ripgrep under the hood.findSearch for files by glob pattern. Returns matching paths relative to the search directory. Respects .gitignore.lsList directory contents. Entries sorted alphabetically with / suffix for directories. Includes dotfiles.

These are organized into presets:

import { codingTools, readOnlyTools } from "@mariozechner/pi-coding-agent";

codingTools;    // [read, bash, edit, write]  - default
readOnlyTools;  // [read, grep, find, ls]     - exploration without modification

Or select individual tools:

import { allBuiltInTools } from "@mariozechner/pi-coding-agent";

// allBuiltInTools.read, allBuiltInTools.bash, allBuiltInTools.edit,
// allBuiltInTools.write, allBuiltInTools.grep, allBuiltInTools.find, allBuiltInTools.ls

const { session } = await createAgentSession({
  model,
  tools: [allBuiltInTools.read, allBuiltInTools.bash, allBuiltInTools.grep],
  sessionManager: SessionManager.inMemory(),
});

createAgentSession

createAgentSession wires everything together - model, tools, session persistence, settings:

import { createAgentSession, SessionManager } from "@mariozechner/pi-coding-agent";
import { getModel, streamSimple } from "@mariozechner/pi-ai";

async function main() {
  const model = getModel("anthropic", "claude-opus-4-5");

  const { session } = await createAgentSession({
    model,
    thinkingLevel: "off",
    sessionManager: SessionManager.inMemory(),
  });

  session.agent.streamFn = streamSimple;

  session.subscribe((event) => {
    if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
      process.stdout.write(event.assistantMessageEvent.delta);
    }
    if (event.type === "tool_execution_start") {
      console.log(`\n[${event.toolName}]`);
    }
  });

  await session.prompt("What files are in the current directory? Summarize the package.json.");
  console.log();

  session.dispose();
}

main();

That’s a working coding agent. It can read your files, run commands, edit code, and write new files. SessionManager.inMemory() means the session lives in memory and disappears when the process exits.

Session persistence

For durable sessions, point the SessionManager at a file:

import * as path from "path";

const sessionFile = path.join(process.cwd(), ".sessions", "my-session.jsonl");
const sessionManager = SessionManager.open(sessionFile);

const { session } = await createAgentSession({
  model,
  sessionManager,
});

Sessions are stored as JSONL files with a tree structure - each entry has an id and parentId. This enables branching: you can navigate to any previous point in the conversation and continue from there without losing history.

SessionManager has several static factory methods. Pick one based on your use case and pass it to createAgentSession:

// Option 1: In-memory (ephemeral, nothing written to disk)
const sessionManager = SessionManager.inMemory();

// Option 2: New persistent session in ~/.pi/agent/sessions/
const sessionManager = SessionManager.create(process.cwd());

// Option 3: Open a specific session file
const sessionManager = SessionManager.open("/path/to/session.jsonl");

// Option 4: Continue the most recent session (or create new if none exists)
const sessionManager = SessionManager.continueRecent(process.cwd());

// Then pass whichever one you chose:
const { session } = await createAgentSession({ model, sessionManager });

You can also list existing sessions for a directory:

const sessions = await SessionManager.list(process.cwd());

Once you have a SessionManager, you rarely need to call its methods directly - createAgentSession handles most of the wiring. But if you’re building custom session logic (like OpenClaw does for multi-channel routing), these are the key methods:

// Reconstruct the conversation from the JSONL file.
// Use this when you need to inspect or display the current conversation
// outside of the agent session (e.g., showing history in a web UI).
const { messages, thinkingLevel, model } = sessionManager.buildSessionContext();

// Get the last entry in the current branch.
// Useful for checking what the most recent message was,
// or grabbing an entry ID to branch from.
const leaf = sessionManager.getLeafEntry();

// Fork the conversation from a specific point.
// Everything after entryId is abandoned (but still in the file).
// The agent continues from that point on the next prompt.
// OpenClaw uses this for "retry from here" flows.
sessionManager.branch(entryId);

// Manually append a message to the session transcript.
// createAgentSession does this automatically during prompt(),
// but you'd use it to inject messages programmatically -
// e.g., adding a system notification or a cron-triggered prompt.
sessionManager.appendMessage(message);

// Get the full tree structure of the session.
// Each node has children, so you can render a branch selector
// or let users navigate conversation history.
const tree = sessionManager.getTree();

OpenClaw uses one session file per channel thread - ~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl - so each conversation is independent and crash-safe (JSONL is append-only; you lose at most one line on a crash).

Using tool factories

The pre-built tool arrays like codingTools and readOnlyTools are singletons that operate on whatever directory your process is running from. If you need tools that operate on a specific directory instead, use the factory functions:

import {
  createCodingTools,
  createReadOnlyTools,
  createReadTool,
  createBashTool,
  createGrepTool,
} from "@mariozechner/pi-coding-agent";

// Create preset groups scoped to a workspace
const customCodingTools = createCodingTools("/path/to/workspace");       // [read, bash, edit, write]
const customReadOnlyTools = createReadOnlyTools("/path/to/workspace");   // [read, grep, find, ls]

// Or create individual tools - there's a factory for each built-in tool
const customRead = createReadTool("/path/to/workspace");
const customBash = createBashTool("/path/to/workspace");
const customGrep = createGrepTool("/path/to/workspace");

Each factory accepts an optional operations object to override the underlying I/O - useful if you want to run tools inside a Docker container, over SSH, or against a virtual filesystem:

// Read files from a remote server instead of the local disk
const remoteRead = createReadTool("/workspace", {
  operations: {
    readFile: async (path) => fetchFileFromRemote(path),
    access: async (path) => checkRemoteFileExists(path),
  },
});

// Execute commands in a Docker sandbox instead of the host
const sandboxedBash = createBashTool("/workspace", {
  operations: {
    exec: async (command, cwd, opts) => runInDockerContainer(command, cwd, opts),
  },
});

OpenClaw uses these factories to create workspace-scoped tools for each agent, then wraps them with additional middleware - permission checks, image normalization for the read tool, and Claude Code parameter compatibility aliases (file_path → path, old_string → oldText).

Custom tools alongside built-in tools

The built-in tools cover file operations and shell commands.

For anything else - deploying, calling APIs, querying databases - define your own tools and pass them via customTools. They’ll be available alongside the defaults:

import { Type } from "@mariozechner/pi-ai";
import type { AgentTool } from "@mariozechner/pi-agent-core";

const deployParams = Type.Object({
  environment: Type.String({ description: "Target environment", default: "staging" }),
});

const deployTool: AgentTool<typeof deployParams> = {
  name: "deploy",
  label: "Deploy",
  description: "Deploy the application to production",
  parameters: deployParams,
  execute: async (_id, params, signal, onUpdate) => {
    onUpdate?.({
      content: [{ type: "text", text: `Deploying to ${params.environment}...` }],
      details: {},
    });

    // Your logic here - call an API, run a script, trigger a CI pipeline, etc.
    await new Promise((resolve) => setTimeout(resolve, 2000));

    return {
      content: [{ type: "text", text: `Deployed to ${params.environment} successfully.` }],
      details: { environment: params.environment, timestamp: Date.now() },
    };
  },
};

const { session } = await createAgentSession({
  model,
  customTools: [deployTool],
  sessionManager: SessionManager.inMemory(),
});

The agent now has read, write, edit, bash and deploy.

Compaction

Long conversations exceed the model’s context window. pi-coding-agent handles this with compaction - summarizing old messages while keeping recent ones:

import { estimateTokens } from "@mariozechner/pi-coding-agent";

// Check how many tokens the conversation uses
const totalTokens = session.messages.reduce(
  (sum, msg) => sum + estimateTokens(msg),
  0
);

// Manually trigger compaction - the optional string guides what the summary should preserve
if (totalTokens > 100_000) {
  await session.compact("Preserve all file paths and code changes.");
}

By default, createAgentSession enables auto-compaction - it triggers automatically when the context approaches the model’s window limit. The full message history stays in the JSONL file; only the in-memory context gets compacted.

Extensions

Tools let the LLM do things. Extensions let you modify how the agent behaves - without the LLM knowing. They hook into lifecycle events that fire during the agent loop: before messages are sent to the LLM, before compaction runs, when a tool is called, when a session starts. The LLM never sees extensions in its context; they operate behind the scenes.

This is where you put logic like: trimming old tool results so the context window stays focused, replacing the default compaction with a custom summarization pipeline, gating tool calls based on permissions, or injecting extra context based on the current state of the conversation.

An extension is a TypeScript module that exports a function receiving an ExtensionAPI:

import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";

export default function myExtension(api: ExtensionAPI): void {
  // Fires before every LLM call. Lets you rewrite the message array.
  api.on("context", (event, ctx) => {
    const pruned = event.messages.filter((msg) => {
      // Drop large tool results older than 10 messages
      if (msg.role === "toolResult" && event.messages.indexOf(msg) < event.messages.length - 10) {
        const text = msg.content.map((c) => (c.type === "text" ? c.text : "")).join("");
        if (text.length > 5000) return false;
      }
      return true;
    });
    return { messages: pruned };
  });

  // Replace the default compaction with your own summarization logic
  api.on("session_before_compact", async (event, ctx) => {
    const summary = await myCustomSummarize(event.messages);
    return { compaction: { summary, firstKeptEntryId: event.firstKeptEntryId, tokensBefore: event.tokensBefore } };
  });

  // Register a user-facing command (not an LLM tool)
  api.registerCommand("stats", {
    description: "Show session statistics",
    handler: async (_args, ctx) => {
      const stats = ctx.session.getSessionStats();
      console.log(`Messages: ${stats.totalMessages}, Cost: $${stats.cost.toFixed(4)}`);
    },
  });
}

Key extension events include context (rewrite messages before the LLM sees them), session_before_compact (customize summarization), tool_call (intercept or gate tool invocations), before_agent_start (inject context or modify the prompt), and session_start/session_switch (react to session changes).

OpenClaw uses extensions for context pruning (silently trimming oversized tool results to save tokens) and compaction safeguards (replacing pi’s default summarization with a multi-stage pipeline that preserves file operation history and tool failure data).

Building something real

Here’s a complete example that ties all three layers together: a codebase assistant that can read your project, answer questions, make changes, and remember the conversation across restarts.

Create assistant.ts:

import {
  createAgentSession,
  SessionManager,
  estimateTokens,
} from "@mariozechner/pi-coding-agent";
import { getModel, streamSimple } from "@mariozechner/pi-ai";
import { Type } from "@mariozechner/pi-ai";
import type { AgentTool } from "@mariozechner/pi-agent-core";
import * as path from "path";
import * as fs from "fs";
import * as readline from "readline";

// --- Custom tool: search the web ---
const webSearchParams = Type.Object({
  query: Type.String({ description: "Search query" }),
});

const webSearchTool: AgentTool<typeof webSearchParams> = {
  name: "web_search",
  label: "Web Search",
  description: "Search the web for documentation, error messages, or general information",
  parameters: webSearchParams,
  execute: async (_id, params) => {
    // In production, call a search API (Brave, Serper, etc.)
    return {
      content: [{ type: "text", text: `[Search results for: "${params.query}" would appear here]` }],
      details: { query: params.query },
    };
  },
};

// --- Session persistence ---
const sessionDir = path.join(process.cwd(), ".sessions");
fs.mkdirSync(sessionDir, { recursive: true });

const sessionFile = path.join(sessionDir, "assistant.jsonl");
const sessionManager = SessionManager.open(sessionFile);

// --- Create the agent session ---
async function createAssistant() {
  const model = getModel("anthropic", "claude-opus-4-5");

  const { session } = await createAgentSession({
    model,
    thinkingLevel: "off",
    sessionManager,
    customTools: [webSearchTool],
  });

  session.agent.streamFn = streamSimple;

  return session;
}

// --- Event handler ---
function attachEventHandlers(session: Awaited<ReturnType<typeof createAssistant>>) {
  session.subscribe((event) => {
    switch (event.type) {
      case "message_update":
        if (event.assistantMessageEvent.type === "text_delta") {
          process.stdout.write(event.assistantMessageEvent.delta);
        }
        break;

      case "tool_execution_start":
        console.log(`\n  [${event.toolName}] ${summarizeArgs(event.args)}`);
        break;

      case "tool_execution_end":
        if (event.isError) {
          console.log(`  ERROR`);
        }
        break;

      case "auto_compaction_start":
        console.log("\n  [compacting context...]");
        break;

      case "agent_end":
        console.log();
        break;
    }
  });
}

function summarizeArgs(args: any): string {
  if (args?.path) return args.path;
  if (args?.command) return args.command.slice(0, 60);
  if (args?.query) return `"${args.query}"`;
  if (args?.pattern) return args.pattern;
  return JSON.stringify(args).slice(0, 60);
}

// --- REPL ---
async function main() {
  const session = await createAssistant();
  attachEventHandlers(session);

  const tokenCount = session.messages.reduce((sum, msg) => sum + estimateTokens(msg), 0);

  console.log("PI Assistant");
  console.log(`  Model: ${session.model?.id}`);
  console.log(`  Session: ${sessionFile}`);
  console.log(`  History: ${session.messages.length} messages, ~${tokenCount} tokens`);
  console.log(`  Tools: ${session.getActiveToolNames().join(", ")}`);
  console.log(`  Type "exit" to quit, "new" to reset session\n`);

  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });

  const ask = () => {
    rl.question("You: ", async (input) => {
      const trimmed = input.trim();

      if (trimmed === "exit") {
        session.dispose();
        rl.close();
        return;
      }

      if (trimmed === "new") {
        await session.newSession();
        console.log("Session reset.\n");
        ask();
        return;
      }

      if (!trimmed) {
        ask();
        return;
      }

      try {
        await session.prompt(trimmed);
      } catch (err: any) {
        console.error(`Error: ${err.message}`);
      }

      ask();
    });
  };

  ask();
}

main();

Run it:

npx tsx assistant.ts

This gives you a persistent coding assistant in ~120 lines. It can read files, run commands, edit code, search the web, and it remembers your conversation across restarts. The session tree in the JSONL file preserves full history even through compaction.

A session looks like:

PI Assistant
  Model: claude-opus-4-5
  Session: /your/project/.sessions/assistant.jsonl
  History: 0 messages, ~0 tokens
  Tools: read, bash, edit, write, web_search

You: What does this project do? Look at the README and main entry point.

  [read] README.md
  [read] src/index.ts

This is a TypeScript library that...

You: Find all TODO comments in the source code.

  [bash] grep -rn "TODO" src/

Found 3 TODOs:
- src/auth.ts:42 - TODO: add token refresh
- src/api.ts:18 - TODO: handle rate limits
- src/index.ts:7 - TODO: add graceful shutdown

You: Fix the token refresh TODO. Implement a proper refresh flow.

  [read] src/auth.ts
  [edit] src/auth.ts

Done. Added a `refreshToken()` function that...

Adapting this for production

OpenClaw takes this same pattern and adds layers for production use:

Multi-provider auth. Instead of a single ANTHROPIC_API_KEY, OpenClaw uses AuthStorage and ModelRegistry to manage credentials across providers and support OAuth flows:

import { AuthStorage, ModelRegistry } from "@mariozechner/pi-coding-agent";

const authStorage = AuthStorage.create(path.join(agentDir, "auth.json"));
const modelRegistry = new ModelRegistry(authStorage, modelsConfigPath);

const { session } = await createAgentSession({
  authStorage,
  modelRegistry,
  model: modelRegistry.find("ollama", "llama3.1:8b"),
  // ...
});

AuthStorage reads from an auth.json file - a flat object keyed by provider name, where each value is either an API key or an OAuth credential:

{
  "anthropic": { "type": "api_key", "key": "sk-ant-..." },
  "openai": { "type": "api_key", "key": "sk-..." },
  "devin": { "type": "api_key", "key": "cog_..." },
  "github-copilot": {
    "type": "oauth",
    "refresh": "gho_xxxxxxxxxxxx",
    "access": "ghu_yyyyyyyyyyyy",
    "expires": 1700000000000
  }
}

The key field can be a literal value, an environment variable name, or a shell command prefixed with ! (e.g., "!op read 'op://vault/openai/key'" for 1Password). OAuth tokens are auto-refreshed when expired.

ModelRegistry reads from a models.json file that defines custom providers and models. This is how you add self-hosted models or providers that aren’t built into pi:

{
  "providers": {
    "ollama": {
      "baseUrl": "http://localhost:11434/v1",
      "api": "openai-completions",
      "apiKey": "ollama",
      "models": [
        { "id": "llama3.1:8b" },
        { "id": "qwen2.5-coder:7b" }
      ]
    },
    "my-company-api": {
      "baseUrl": "https://llm.internal.company.com/v1",
      "api": "openai-completions",
      "apiKey": "COMPANY_LLM_KEY",
      "authHeader": true,
      "models": [
        { "id": "internal-model-v2" }
      ]
    }
  }
}

Models defined here show up alongside the built-in catalog. modelRegistry.find("ollama", "llama3.1:8b") returns a fully typed Model you can pass to createAgentSession.

Stream middleware. session.agent.streamFn is the function the agent calls every time it needs to talk to an LLM. By default it’s streamSimple, but you can wrap it to inject headers, tweak parameters, or add logging on a per-provider basis.

OpenClaw uses this to add OpenRouter attribution headers and enable Anthropic prompt caching:

import { streamSimple } from "@mariozechner/pi-ai";
import type { StreamFn } from "@mariozechner/pi-agent-core";

const wrappedStreamFn: StreamFn = (model, context, options) => {
  const extraHeaders: Record<string, string> = {};

  // OpenRouter uses these for their public app rankings/leaderboard
  if (model.provider === "openrouter") {
    extraHeaders["X-Title"] = "My App";
    extraHeaders["HTTP-Referer"] = "https://myapp.com";
  }

  return streamSimple(model, context, {
    ...options,
    headers: { ...options?.headers, ...extraHeaders },
    cacheRetention: model.provider === "anthropic" ? "long" : "none",
  });
};

session.agent.streamFn = wrappedStreamFn;

Tool customization. The default built-in tools operate on process.cwd(), which is fine for a local CLI.

But in a multi-user product like OpenClaw, each agent session needs to be locked to a specific workspace directory so users can’t read or write outside their project. OpenClaw uses the tool factories to rebuild the file tools with a workspace root, keeping the same tool behavior but scoping all paths:

import {
  codingTools,
  readTool,
  createReadTool,
  createWriteTool,
  createEditTool,
} from "@mariozechner/pi-coding-agent";
import type { AgentTool } from "@mariozechner/pi-agent-core";

function buildTools(workspace: string): AgentTool[] {
  return (codingTools as AgentTool[]).map((tool) => {
    if (tool.name === readTool.name) {
      return createReadTool(workspace);
    }
    if (tool.name === "write") {
      return createWriteTool(workspace);
    }
    if (tool.name === "edit") {
      return createEditTool(workspace);
    }
    return tool; // bash stays as-is
  });
}

Event routing. When the agent runs, it emits events - text tokens streaming in, tool calls starting and finishing, the agent completing its turn. In a terminal app, you’d just print these to stdout. But OpenClaw runs agents on behalf of users who are chatting via Telegram, Discord, or Slack, so it needs to translate these events into platform-specific messages. session.subscribe() gives you a callback for every event, and you decide what to do with each one:

session.subscribe((event) => {
  switch (event.type) {
    case "message_update":
      if (event.assistantMessageEvent.type === "text_delta") {
        // Tokens arrive one at a time - buffer them, then send as one message
        messageBuffer.append(event.assistantMessageEvent.delta);
      }
      break;

    case "tool_execution_start":
      // Send tool call notification to the channel
      channel.sendNotification(`Running ${event.toolName}...`);
      break;

    case "agent_end":
      // Flush remaining buffered text
      messageBuffer.flush();
      break;
  }
});

Adding a terminal UI

The assistant.ts example uses readline for input - it works, but you get no markdown rendering, no autocomplete, and raw process.stdout.write for streaming. pi-tui replaces all of that with a proper terminal UI: markdown with syntax highlighting, an editor with slash command and file path autocomplete, a loading spinner, and flicker-free differential rendering.

Here’s the same assistant upgraded to pi-tui. Create assistant-tui.ts:

import {
  createAgentSession,
  SessionManager,
  estimateTokens,
} from "@mariozechner/pi-coding-agent";
import { getModel, streamSimple } from "@mariozechner/pi-ai";
import { Type } from "@mariozechner/pi-ai";
import type { AgentTool } from "@mariozechner/pi-agent-core";
import {
  TUI,
  ProcessTerminal,
  Editor,
  Markdown,
  Text,
  Loader,
  CombinedAutocompleteProvider,
} from "@mariozechner/pi-tui";
import type { EditorTheme, MarkdownTheme } from "@mariozechner/pi-tui";
import chalk from "chalk";
import * as path from "path";
import * as fs from "fs";

// --- Themes ---
const markdownTheme: MarkdownTheme = {
  heading: (s) => chalk.bold.cyan(s),
  link: (s) => chalk.blue(s),
  linkUrl: (s) => chalk.dim(s),
  code: (s) => chalk.yellow(s),
  codeBlock: (s) => chalk.green(s),
  codeBlockBorder: (s) => chalk.dim(s),
  quote: (s) => chalk.italic(s),
  quoteBorder: (s) => chalk.dim(s),
  hr: (s) => chalk.dim(s),
  listBullet: (s) => chalk.cyan(s),
  bold: (s) => chalk.bold(s),
  italic: (s) => chalk.italic(s),
  strikethrough: (s) => chalk.strikethrough(s),
  underline: (s) => chalk.underline(s),
};

const editorTheme: EditorTheme = {
  borderColor: (s) => chalk.dim(s),
  selectList: {
    selectedPrefix: (s) => chalk.blue(s),
    selectedText: (s) => chalk.bold(s),
    description: (s) => chalk.dim(s),
    scrollInfo: (s) => chalk.dim(s),
    noMatch: (s) => chalk.dim(s),
  },
};

// --- Custom tool ---
const webSearchParams = Type.Object({
  query: Type.String({ description: "Search query" }),
});

const webSearchTool: AgentTool<typeof webSearchParams> = {
  name: "web_search",
  label: "Web Search",
  description: "Search the web for documentation, error messages, or general information",
  parameters: webSearchParams,
  execute: async (_id, params) => ({
    content: [{ type: "text", text: `[Search results for: "${params.query}" would appear here]` }],
    details: { query: params.query },
  }),
};

// --- Session persistence ---
const sessionDir = path.join(process.cwd(), ".sessions");
fs.mkdirSync(sessionDir, { recursive: true });
const sessionFile = path.join(sessionDir, "assistant.jsonl");

// --- TUI setup ---
const tui = new TUI(new ProcessTerminal());

tui.addChild(new Text(chalk.bold("PI Assistant") + chalk.dim(" (Ctrl+C to exit)\n")));

const editor = new Editor(tui, editorTheme);
editor.setAutocompleteProvider(
  new CombinedAutocompleteProvider(
    [
      { name: "new", description: "Reset the session" },
      { name: "exit", description: "Quit the assistant" },
    ],
    process.cwd(),
  ),
);
tui.addChild(editor);
tui.setFocus(editor);

// --- Main ---
async function main() {
  const model = getModel("anthropic", "claude-opus-4-5");
  const sessionManager = SessionManager.open(sessionFile);

  const { session } = await createAgentSession({
    model,
    thinkingLevel: "off",
    sessionManager,
    customTools: [webSearchTool],
  });

  session.agent.streamFn = streamSimple;

  // Show session info
  const tokenCount = session.messages.reduce((sum, msg) => sum + estimateTokens(msg), 0);
  const children = tui.children;
  children.splice(children.length - 1, 0, new Text(
    chalk.dim(`  Model: ${model.id}\n`) +
    chalk.dim(`  Session: ${sessionFile}\n`) +
    chalk.dim(`  History: ${session.messages.length} messages, ~${tokenCount} tokens\n`) +
    chalk.dim(`  Tools: ${session.getActiveToolNames().join(", ")}\n`),
  ));
  tui.requestRender();

  // Streaming state
  let streamingMarkdown: Markdown | null = null;
  let streamingText = "";
  let loader: Loader | null = null;
  let isRunning = false;

  // Subscribe to agent events
  session.subscribe((event) => {
    switch (event.type) {
      case "agent_start":
        isRunning = true;
        editor.disableSubmit = true;
        loader = new Loader(tui, (s) => chalk.cyan(s), (s) => chalk.dim(s), "Thinking...");
        children.splice(children.length - 1, 0, loader);
        tui.requestRender();
        break;

      case "message_update":
        if (event.assistantMessageEvent.type === "text_delta") {
          // Remove loader on first text
          if (loader) {
            tui.removeChild(loader);
            loader = null;
          }
          // Create or update the streaming markdown component
          streamingText += event.assistantMessageEvent.delta;
          if (!streamingMarkdown) {
            streamingMarkdown = new Markdown(streamingText, 1, 0, markdownTheme);
            children.splice(children.length - 1, 0, streamingMarkdown);
          } else {
            streamingMarkdown.setText(streamingText);
          }
          tui.requestRender();
        }
        break;

      case "tool_execution_start": {
        if (loader) {
          tui.removeChild(loader);
          loader = null;
        }
        const args = event.args?.path || event.args?.command?.slice(0, 60) || event.args?.query || "";
        const toolMsg = new Text(chalk.dim(`  [${event.toolName}] ${args}`));
        children.splice(children.length - 1, 0, toolMsg);
        tui.requestRender();
        break;
      }

      case "agent_end":
        if (loader) {
          tui.removeChild(loader);
          loader = null;
        }
        streamingMarkdown = null;
        streamingText = "";
        isRunning = false;
        editor.disableSubmit = false;
        tui.requestRender();
        break;
    }
  });

  // Handle input submission
  editor.onSubmit = async (value: string) => {
    if (isRunning) return;
    const trimmed = value.trim();
    if (!trimmed) return;

    if (trimmed === "/exit") {
      session.dispose();
      tui.stop();
      process.exit(0);
    }

    if (trimmed === "/new") {
      await session.newSession();
      children.splice(2, children.length - 3); // Keep header, info, and editor
      children.splice(children.length - 1, 0, new Text(chalk.dim("  Session reset.\n")));
      tui.requestRender();
      return;
    }

    // Add user message to chat
    const userMsg = new Markdown(value, 1, 0, markdownTheme, (s) => chalk.bold(s));
    children.splice(children.length - 1, 0, userMsg);
    tui.requestRender();

    // Send to agent
    try {
      await session.prompt(trimmed);
    } catch (err: any) {
      children.splice(children.length - 1, 0, new Text(chalk.red(`Error: ${err.message}`)));
      editor.disableSubmit = false;
      tui.requestRender();
    }
  };

  tui.start();
}

main();

Run it:

npx tsx assistant-tui.ts

The key differences from the readline version:

• Markdown rendering. Agent responses render with syntax-highlighted code blocks, bold, italics, lists, and links - instead of raw text dumped to stdout.

• Streaming via setText. As tokens arrive, we append to a string and call streamingMarkdown.setText(). The TUI’s differential renderer updates only the changed lines - no flicker, no screen clearing.

• Editor with autocomplete. Type / and you get a dropdown of slash commands. Press Tab for file path completion. Multi-line input with Shift+Enter.

• Loading spinner. The Loader component shows an animated spinner while the agent thinks, then removes itself when text starts streaming.

• No manual cursor management. The TUI handles terminal state, cursor positioning, and cleanup. No process.stdout.write calls scattered through your event handler.

The architecture is the same - createAgentSession + session.subscribe() + session.prompt(). The only change is how you render the events: instead of writing to stdout, you add and update Markdown, Text, and Loader components in the TUI’s component tree.

What’s next

This guide covered the four packages you need to build a terminal-based agent. The remaining pi-mono packages extend the system in other directions:

• pi-web-ui - Lit web components for browser-based chat interfaces. Drop-in ChatPanel component with streaming, file attachments, and artifact rendering (HTML/SVG/Markdown in sandboxed iframes).

• pi-mom - A Slack bot that delegates messages to pi-coding-agent. Per-channel agent isolation, Docker sandboxing, scheduled events, and self-managing tool installation.

• pi-pods - CLI for deploying open-source models on GPU pods via vLLM. Supports DataCrunch, RunPod, Vast.ai, and bare metal. Each deployed model exposes an OpenAI-compatible endpoint that pi-ai can consume.

The pi-coding-agent docs cover the full extension API, skills system, and CLI usage. The pi-mono AGENTS.md has detailed instructions for adding new LLM providers.

For a production example of building on these packages, see OpenClaw - a multi-channel AI assistant that uses all four core packages to run agents across WhatsApp, Telegram, Discord, Slack, Signal, iMessage, Google Chat, Microsoft Teams, and more, with shared memory and persistent sessions.

Originally posted on X.

Hi I’m Nader and I recently joined @cognition, the creators of @DevinAI.

Devin is a cloud agent platform for engineering teams. You work with Devin like a teammate - give it tasks, review its PRs, and let it handle your backlog.

Last week, we merged 659 Devin PRs into our own codebase, up from 154 in our best week in 2025.

Many of you know Devin as the web app. Internally, we use it across every interface (web, Slack, Linear, CLI, API) depending on where the work starts. This post covers how we leverage all of them.

Core Experience

The setup is this: we add any of the codebases we’d like Devin to manage. We’re then given a unified interface where we can work across all of our repos using natural language.

It’s designed as a conversational interface, so we can chat with it the same way we’d message a teammate, whether from Slack, a Linear or Jira ticket, or the web app. Tag @ Devin in any channel. Include attachments if needed. Communicate back and forth as we would in the regular chat interface.

A powerful result is that anyone is able to contribute regardless of their technical expertise or role in the company, they don’t need to understand and set up Git or any command line tools to start contributing to our codebases.

Tag @ Devin with a request and we get a PR we can review and test out. If someone notices out of date documentation or a bug for example, they send a short message in Slack to get it fixed and move on with their day.

This removes friction and barriers for rapid iteration and polish,and results in less context switching.

And when engineers see what their teammates are accomplishing with Devin, on the same codebase they work on every day, they have the “Oh, really? Devin can do that?” moment, so it spreads organically.

Ask Devin (Codebase Q&A)

Once a repository is added to Devin, it’s automatically indexed. Ask Devin becomes a window into that codebase.

We use this constantly for scoping work before starting sessions. The workflow: use Ask Devin to explore the code and clarify a goal, then start a session directly from the search interface.

Devin starts with clear context from our exploration, and the prompt is automatically tailored to our task.

This same workflow applies with Jira or Linear integrations. Tag Devin on a ticket. Devin analyzes the task, searches the codebase, and plans its approach. It generates a high-quality session prompt automatically.

Automated Code Review

As we ship more code with agents, the bottleneck shifted from writing code to reviewing it. Devin Review turns large, complex GitHub PRs into intuitively organized diffs and precise explanations.

We use it for every PR now.

Every time Devin posts a PR in Slack, it includes a Devin Review link, so the organized diff is always one click away.

What makes Devin Review useful:

• Autofix. If Devin Review or a GitHub bot flags bugs, Devin automatically fixes the PR. Devin also tackles CI/lint issues until all checks pass, closing the agent loop.

• Smart diff organization. Groups changes logically, putting related edits together instead of alphabetical order.

• Copy and move detection. Detects when code has been copied or moved and displays changes cleanly, instead of full deletes and inserts.

• Bug Catcher. Automatically analyzes PRs for potential issues and labels them by confidence level. Severe bugs require immediate attention. Non-severe bugs should still be reviewed. Flags are informational annotations.

• Codebase-aware chat. Ask questions about the PR and get answers with relevant context from the rest of the codebase.

For any GitHub PR link, you can replace github.com with devinreview.com in the URL.

Once Auto-Review is configured, Devin starts automatically reviewing PRs when they’re opened, when new commits are pushed, or when someone is added as a reviewer.

Design System

Design systems drift. Someone hardcodes a hex value, another person builds a one-off button, and suddenly we’re maintaining multiple sources of truth. We handle this two ways.

First, anyone can fix violations the moment they spot them. Tag Devin in Slack with a screenshot and it migrates the component to match the design system.

Second, we run a daily audit. Every morning Devin scans PRs merged in the last 24 hours, flags hardcoded colors, non-standard spacing, and components that should use the shared library. It creates Linear tickets for each violation, and optionally opens fix PRs automatically.

The combination means violations get caught whether someone notices them or not.

Bug Triage Automation

When a bug lands in Linear, someone has to stop what they’re doing to investigate—reading the ticket, searching the codebase, checking recent commits—before any actual fixing happens. We automated that entire triage step.

We set up a !triage-bug playbook that captures how our engineers actually investigate: read the report, search for relevant code paths, check git history, then summarize findings with root cause and suggested fix. The automation fires when anyone adds the Bug label to a ticket—no assignment needed.

A ticket like “500 error on /contact after Friday’s deploy” turns into Devin automatically finding the file, spotting a recent regex refactor in git log, and posting a summary back to Linear: root cause, affected files, suggested fix approach.

We connect the Datadog MCP so Devin checks logs during its investigation. By the time an engineer picks up a bug, the investigation is already done.

End-to-End Bug Debugging

Some bugs need more than triage. They need someone to pull logs, check the database, trace the code change, and write a fix. We connected Devin to Datadog and gave it read-only database access so it can run full investigations.

When a bug report comes in (like “Pro users seeing ‘undefined’ on the billing page since Friday’s deploy”), Devin pulls error logs from Datadog, queries the read replica to verify data state, traces the breaking commit in git history, writes a fix with a regression test, and opens a PR.

The investigation that used to pull an engineer off their work for an hour now happens in the background. We review the PR, not the logs.

DANA (Data Analyst Agent)

DANA is a specialized version of Devin optimized for querying databases, analyzing data, and creating visualizations.

We use it for questions about our data warehouse, building dashboards, and answering data questions without pulling an engineer off their work. It’s become a go-to for non-engineering tasks too, like the “click a bunch of buttons to fill out a report” work that used to eat up time.

We’re able to access DANA from the web app by clicking the agent picker dropdown, or from Slack using /dana or @Devin !dana followed by our question.

We’ve learned to be specific about metrics, include time periods, and ask for visualizations when they’d help.

DANA connects to our data warehouse through MCP—Redshift, PostgreSQL, Snowflake, BigQuery, whatever we’re running—and maintains its own database knowledge so it already understands our schema before we ask anything. It’s optimized for concise, metrics-focused answers with built-in seaborn visualizations, so we get charts and insights back fast instead of waiting for an engineer to context-switch into a SQL client.

We’ve found it especially useful for the kind of ad-hoc questions that used to sit in someone’s queue for days. Questions like “why did signups drop Tuesday?” or “break down consumption by enterprise vs self-serve” can be answered by anyone on the team just asking in Slack, with the SQL included so we can validate the logic.

DeepWiki

With DeepWiki, Devin automatically indexes all repos and produces wikis with architecture diagrams, links to sources, and summaries of the codebase. Ask Devin uses information in the Wiki to better understand and find relevant context.

For public repos, deepwiki.com automatically generates architecture diagrams, source links, and documentation, no setup required.

We also maintain a free DeepWiki MCP.

Playbooks

A Playbook is like a custom system prompt for a repeated task. If we find ourselves repeating the same instructions across multiple sessions, that’s when we create a Playbook.

Once anyone succeeds with Devin, others can replicate that success. A good Playbook includes:

• The outcome we want Devin to achieve

• The steps required to get there

• Specifications describing postconditions

• Advice to correct Devin’s priors

• Forbidden actions

• Any required input or context from the person kicking it off

We use Playbooks for complex recurring work—ingesting data into Redshift, running database migrations, integrating with Stripe, Plaid, and Modal.

MCP Marketplace

MCP enables Devin to use hundreds of external tools and data sources. We use MCPs to dig through Sentry, Datadog, and Vercel logs. Connect database MCPs for data analysis in Slack. Pull context from tools like Notion, Airtable, and Linear.

Many can be enabled with a single click—Vercel, Atlassian, Notion, Sentry, Neon, Asana, Jam, and more.

For example, we chart cumulative Linear integrations across all orgs by tagging Devin in Slack with the Redshift MCP—this gives us a weekly breakdown, key observations, and a Metabase link we can share.

Session Insights

Session Insights analyzes completed Devin sessions and provides actionable recommendations for improvement.

After Devin completes a task, Session Insights examines:

• Issues and challenges (technical problems, communication gaps, scope creep)

• Session timeline with key milestones and efficiency metrics

• Action items including immediate improvements and process optimizations

• Improved prompt suggestions with enhanced instructions

We use insights from one session to inform the next. We can spin up new sessions directly from the insights using the improved prompts. Over time, sessions get more efficient.

API Access

Devin exposes a full REST API, so agents don’t need a human in the loop to start working. We connect Devin to our existing systems and trigger sessions programmatically:

• A crash log lands from Sentry → Devin investigates and opens a PR

• A bug report is filed → Devin reproduces, diagnoses, and patches

• A deployment fails → Devin analyzes logs and suggests a fix

• A code review is requested → Devin reviews and leaves comments

Where Devin Excels

Devin can take on most engineering work, including complex tasks. Success scales with specificity. Well-scoped tasks with clear criteria get the best outcomes.

Tasks we consistently use Devin for:

• High volume iterative improvements

• Bug fixes and edge cases

• Improving test coverage

• Investigating CI failures

• Lint errors and CVE remediation

• PR review

• Maintaining documentation

• Remediating security vulnerabilities from static analysis

• Codebase Q&A

Tips for Complex Tasks

• Large-scale challenges should be broken into smaller, isolated tasks across separate sessions.

• Devin excels at building interfaces that work; styling them beautifully is still a human strength.

• Mobile development works, but Devin doesn’t have a phone to test with.

• For anything requiring extensive testing and validation, we make sure verification mechanisms are in place.

Getting Started

Minimum Setup

1. Sign up at app.devin.ai

2. Connect your GitHub, GitLab, or Bitbucket

3. Add your first repository

4. Start a session with a simple task

Scaling Up As you get comfortable:

• Add Knowledge to teach Devin your codebase conventions

• Create Playbooks for repeated tasks

• Connect Slack for inline collaboration

• Enable MCPs for your tools

• Use Ask Devin to scope complex work before starting sessions

Treat Devin like a team member. Give it context. Teach it your conventions. Let it handle the backlog while you focus on the work that requires senior judgment. An AI software engineer with clear context, working autonomously on well-scoped tasks, is a force multiplier.

Built by the team at @cognition. If you’re building with @DevinAI, we’d love to hear about it.

I know everyone isn’t like this, but I’ve talked to enough people to know that this is a common feeling to have.

What I can say is this: the most important things that have happened in my career and life have been the result of taking action in the face of discomfort. It’s almost a gauge at this point, balancing it with my gut feeling + logic.

If my gut says do it and logically I agree with it, then I do it no matter how uncomfortable it feels. And it’s almost at that point I’ve learned that the more uncomfortable it feels, the more I should do it.

Yes there have been very painful situations that were due to me making very public mistakes, but the good by far has outweighed the bad.

I’m writing this to you but also as a reminder to my future self to stop waiting for the fear to go away, because it doesn’t, we just get better at moving with it.

Originally posted on X

What makes OpenClaw powerful is surprisingly simple: it’s a gateway that connects an AI agent to your messaging apps, gives it tools to interact with your computer, and lets it remember who you are across conversations.

The complexity comes from handling multiple channels simultaneously, managing persistent sessions, coordinating multiple agents, and making the whole thing reliable enough to run 24/7 on your machine.

In this post, I’ll start from scratch and build up to OpenClaw’s architecture step by step, showing how you could have invented it yourself from first principles, using nothing but a messaging API, an LLM, and the desire to make AI actually useful outside the chat window.

End goal: understand how persistent AI assistants work, so you can build your own.

First, let’s establish the problem

When you use ChatGPT or Claude in a browser, there are several limitations:

It’s stateless. Every conversation starts from zero. It doesn’t know your name, your preferences, what you asked yesterday, or what project you’re working on. You’re constantly re-explaining context.

It’s passive. You go to it. It never comes to you. It can’t wake up at 7am and brief you on your calendar, monitor your email, or run a recurring task. It only works when you’re sitting in front of it.

It’s isolated. It can’t run commands on your machine, browse the web for you, control your apps, or send messages on your behalf. It lives in a text box with no hands.

It’s single-channel. Your real life happens across WhatsApp, Telegram, Discord, Slack, iMessage - but the AI lives in its own separate tab. There’s no way to text it where you already are, let alone have it maintain one continuous memory across all those surfaces.

What if instead, you had an AI that:

• Lived in the messaging apps you already use - all of them, with shared memory

• Remembered your preferences, your projects, and your past conversations across sessions

• Could run commands on your computer, browse the web, and control a real browser

• Woke up on a schedule to handle recurring tasks without being asked

• Ran on your own hardware - your laptop, a VPS, a Mac Mini - always on, under your control

This is what OpenClaw does. It’s not a chatbot - it’s a personal AI assistant with a persistent identity, tools, and presence across every channel you use.

Let’s build one from scratch.

The Simplest Possible Bot

Let’s start with the absolute minimum: an AI that responds to messages on Telegram.

# bot-v0.py - The simplest possible AI bot
import os
import anthropic
from telegram import Update
from telegram.ext import Application, MessageHandler, filters

client = anthropic.Anthropic()

async def handle_message(update: Update, context):
    user_message = update.message.text

    response = client.messages.create(
        model=”claude-sonnet-4-5-20250929”,
        max_tokens=1024,
        messages=[{”role”: “user”, “content”: user_message}]
    )

    await update.message.reply_text(response.content[0].text)

app = Application.builder().token(os.getenv(”TELEGRAM_BOT_TOKEN”)).build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()

Run it, send a message on Telegram, and the AI responds. Simple.

But this is basically a worse version of the Claude web interface. Every message is independent. No memory. No tools. No personality.

What if we gave it memory?

Goal: Persistent Sessions

A problem with our simple bot is statelessness. Every message is a fresh conversation. Ask it “what did I say earlier?” and it has no idea.

The fix is sessions. Keep a conversation history per user.

# bot-v1.py - Bot with persistent sessions
import json
import os
import anthropic
from telegram import Update
from telegram.ext import Application, MessageHandler, filters

client = anthropic.Anthropic()
SESSIONS_DIR = “./sessions”
os.makedirs(SESSIONS_DIR, exist_ok=True)

def get_session_path(user_id):
    return os.path.join(SESSIONS_DIR, f”{user_id}.jsonl”)

def load_session(user_id):
    “”“Load conversation history from disk.”“”
    path = get_session_path(user_id)
    messages = []
    if os.path.exists(path):
        with open(path, “r”) as f:
            for line in f:
                if line.strip():
                    messages.append(json.loads(line))
    return messages

def append_to_session(user_id, message):
    “”“Append a single message to the session file.”“”
    path = get_session_path(user_id)
    with open(path, “a”) as f:
        f.write(json.dumps(message) + “\n”)

def save_session(user_id, messages):
    “”“Overwrite the session file with the full message list.”“”
    path = get_session_path(user_id)
    with open(path, “w”) as f:
        for message in messages:
            f.write(json.dumps(message) + “\n”)

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)
    user_message = update.message.text

    # Load existing conversation
    messages = load_session(user_id)

    # Add new user message
    user_msg = {”role”: “user”, “content”: user_message}
    messages.append(user_msg)
    append_to_session(user_id, user_msg)

    # Call the AI with full history
    response = client.messages.create(
        model=”claude-sonnet-4-5-20250929”,
        max_tokens=4096,
        messages=messages
    )

    # Save assistant response
    assistant_msg = {”role”: “assistant”, “content”: response.content[0].text}
    append_to_session(user_id, assistant_msg)

    await update.message.reply_text(response.content[0].text)

app = Application.builder().token(os.getenv(”TELEGRAM_BOT_TOKEN”)).build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()

Now you can have an actual conversation:

You: My name is Nader
Bot: Nice to meet you, Nader!

[hours later...]

You: What's my name?
Bot: Your name is Nader!

The key insight is the JSONL format. Each line is one message. Append-only. If the process crashes mid-write, you lose at most one line. This is exactly what OpenClaw uses for session transcripts:

~/.openclaw/agents/<agentId>/sessions/<sessionId>.jsonl

Each session maps to a file. Each file is a conversation. Restart the process and everything is still there.

But we’ll hit a problem: conversations grow. Eventually they’ll exceed the model’s context window. We’ll come back to that.

Goal: Adding a Personality (SOUL.md)

Our bot works, but it has no personality. It’s a generic AI assistant. What if we wanted it to be someone?

OpenClaw solves this with SOUL.md: a markdown file that defines the agent’s identity, behavior, and boundaries.

# bot-v2.py - Bot with personality

SOUL = “”“
# Who You Are

**Name:** Jarvis
**Role:** Personal AI assistant

## Personality
- Be genuinely helpful, not performatively helpful
- Skip the “Great question!” - just help
- Have opinions. You’re allowed to disagree
- Be concise when needed, thorough when it matters

## Boundaries
- Private things stay private
- When in doubt, ask before acting externally
- You’re not the user’s voice - be careful about sending messages on their behalf

## Memory
Remember important details from conversations.
Write them down if they matter.
“”“

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)
    messages = load_session(user_id)

    user_msg = {”role”: “user”, “content”: update.message.text}
    messages.append(user_msg)
    append_to_session(user_id, user_msg)

    response = client.messages.create(
        model=”claude-sonnet-4-5-20250929”,
        max_tokens=4096,
        system=SOUL,  # <-- personality injected here
        messages=messages
    )

    assistant_msg = {”role”: “assistant”, “content”: response.content[0].text}
    append_to_session(user_id, assistant_msg)

    await update.message.reply_text(response.content[0].text)

Now instead of a generic assistant, you’re talking to Jarvis. The SOUL gets injected as the system prompt on every API call.

In OpenClaw, the SOUL.md lives in the agent’s workspace:

~/.openclaw/workspace/SOUL.md

It gets loaded at session start and injected into the system prompt. You can write anything you want in there. Give the agent an origin story. Define its core philosophy. List its behavioral rules.

The more specific your SOUL, the more consistent the agent’s behavior. “Be helpful” is vague. “Be the assistant you’d actually want to talk to. Concise when needed, thorough when it matters. Not a corporate drone. Not a sycophant. Just... good.” - that gives the model something to work with.

Goal: Adding Tools

A bot that can only talk is limited. What if it could do things?

The core idea: give the AI structured tools and let it decide when to use them.

import subprocess

TOOLS = [
    {
        “name”: “run_command”,
        “description”: “Run a shell command on the user’s computer”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “command”: {”type”: “string”, “description”: “The command to run”}
            },
            “required”: [”command”]
        }
    },
    {
        “name”: “read_file”,
        “description”: “Read a file from the filesystem”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “path”: {”type”: “string”, “description”: “Path to the file”}
            },
            “required”: [”path”]
        }
    },
    {
        “name”: “write_file”,
        “description”: “Write content to a file”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “path”: {”type”: “string”, “description”: “Path to the file”},
                “content”: {”type”: “string”, “description”: “Content to write”}
            },
            “required”: [”path”, “content”]
        }
    },
    {
        “name”: “web_search”,
        “description”: “Search the web for information”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “query”: {”type”: “string”, “description”: “Search query”}
            },
            “required”: [”query”]
        }
    }
]

def execute_tool(name, input):
    if name == “run_command”:
        result = subprocess.run(
            input[”command”], shell=True,
            capture_output=True, text=True, timeout=30
        )
        return result.stdout + result.stderr

    elif name == “read_file”:
        with open(input[”path”], “r”) as f:
            return f.read()

    elif name == “write_file”:
        with open(input[”path”], “w”) as f:
            f.write(input[”content”])
        return f”Wrote to {input[’path’]}”

    elif name == “web_search”:
        # Simplified - use a real search API in practice
        return f”Search results for: {input[’query’]}”

    return f”Unknown tool: {name}”

Now we need the agent loop. When the AI wants to use a tool, we execute it and feed the result back:

def serialize_content(content):
    “”“Convert API response content blocks to JSON-serializable dicts.”“”
    serialized = []
    for block in content:
        if hasattr(block, “text”):
            serialized.append({”type”: “text”, “text”: block.text})
        elif block.type == “tool_use”:
            serialized.append({
                “type”: “tool_use”,
                “id”: block.id,
                “name”: block.name,
                “input”: block.input
            })
    return serialized

def run_agent_turn(messages, system_prompt):
    “”“Run one full agent turn (may involve multiple tool calls).”“”
    while True:
        response = client.messages.create(
            model=”claude-sonnet-4-5-20250929”,
            max_tokens=4096,
            system=system_prompt,
            tools=TOOLS,
            messages=messages
        )

        content = serialize_content(response.content)

        # If the AI is done (no tool use), return the text
        if response.stop_reason == “end_turn”:
            text = “”
            for block in response.content:
                if hasattr(block, “text”):
                    text += block.text
            messages.append({”role”: “assistant”, “content”: content})
            return text, messages

        # Process tool calls
        if response.stop_reason == “tool_use”:
            messages.append({”role”: “assistant”, “content”: content})

            tool_results = []
            for block in response.content:
                if block.type == “tool_use”:
                    print(f”  Tool: {block.name}({json.dumps(block.input)})”)
                    result = execute_tool(block.name, block.input)
                    tool_results.append({
                        “type”: “tool_result”,
                        “tool_use_id”: block.id,
                        “content”: str(result)
                    })

            messages.append({”role”: “user”, “content”: tool_results})

Now we update handle_message to use the agent loop instead of calling the API directly:

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)
    messages = load_session(user_id)
    messages.append({”role”: “user”, “content”: update.message.text})

    response_text, messages = run_agent_turn(messages, SOUL)

    save_session(user_id, messages)
    await update.message.reply_text(response_text)

Now you can text your bot:

You: Create a file called hello.py that prints hello world, then run it

Bot: [uses write_file to create hello.py]
    [uses run_command to execute it]
    Done! I created hello.py and ran it. Output: "hello world"

The AI decided which tools to use, in what order, and synthesized the results into a natural response. All through a Telegram message.

OpenClaw’s production tool catalog is much larger — browser automation, inter-agent messaging, sub-agent spawning, and more -= but every tool follows this exact pattern: a schema, a description, and an execution function.

Goal: Permission Controls

We’re executing commands from Telegram messages. That’s terrifying. What if someone gets access to your Telegram account and tells the bot to rm -rf /?

We need a permission system. OpenClaw’s approach: an approval allowlist that remembers what you’ve approved.

We add these helpers alongside our existing code, then update the run_command case inside execute_tool to use them:

import re

SAFE_COMMANDS = {”ls”, “cat”, “head”, “tail”, “wc”, “date”, “whoami”, “echo”}
DANGEROUS_PATTERNS = [r”\brm\b”, r”\bsudo\b”, r”\bchmod\b”, r”\bcurl.*\|.*sh”]

# Persistent allowlist
APPROVALS_FILE = “./exec-approvals.json”

def load_approvals():
    if os.path.exists(APPROVALS_FILE):
        with open(APPROVALS_FILE) as f:
            return json.load(f)
    return {”allowed”: [], “denied”: []}

def save_approval(command, approved):
    approvals = load_approvals()
    key = “allowed” if approved else “denied”
    if command not in approvals[key]:
        approvals[key].append(command)
    with open(APPROVALS_FILE, “w”) as f:
        json.dump(approvals, f, indent=2)

def check_command_safety(command):
    “”“Returns ‘safe’, ‘approved’, or ‘needs_approval’.”“”
    base_cmd = command.strip().split()[0] if command.strip() else “”
    if base_cmd in SAFE_COMMANDS:
        return “safe”

    approvals = load_approvals()
    if command in approvals[”allowed”]:
        return “approved”

    for pattern in DANGEROUS_PATTERNS:
        if re.search(pattern, command):
            return “needs_approval”

    return “needs_approval”

Now update the run_command case in execute_tool to check permissions before executing:

    if name == “run_command”:
        cmd = input[”command”]
        safety = check_command_safety(cmd)

        if safety == “needs_approval”:
            # In a real bot, you’d prompt the user via Telegram
            # and wait for their response. For simplicity, we log and deny.
            print(f”  ⚠️  Blocked: {cmd} (needs approval)”)
            return “Permission denied. Command requires approval.”

        result = subprocess.run(
            cmd, shell=True, capture_output=True,
            text=True, timeout=30
        )
        return result.stdout + result.stderr

When a command is safe or previously approved, it runs immediately. When it’s not, the agent gets told “permission denied” and can try a different approach. The approval gets persisted to exec-approvals.json, so you’re never asked twice for the same command.

OpenClaw extends this with glob patterns (approve git * once) and a three-tier model: “ask” (prompt user), “record” (log but allow), and “ignore” (auto-allow).

Goal: The Gateway

Here’s where it gets interesting. So far we have a Telegram bot. But what if you also want the AI on Discord? And WhatsApp? And Slack?

You could write separate bots for each platform. But then you’d have separate sessions, separate memory, separate configurations. The AI on Telegram wouldn’t know what you discussed on Discord.

The solution: a gateway. One central process that manages all channels.

Look at what we already have. Our run_agent_turn function doesn’t know anything about Telegram. It takes messages and returns text. That’s the key — the agent logic is already decoupled from the channel.

To prove it, let’s add a second interface. We’ll add a simple HTTP API alongside our Telegram bot, both talking to the same agent and the same sessions:

from flask import Flask, request, jsonify
import threading

flask_app = Flask(__name__)

@flask_app.route(”/chat”, methods=[”POST”])
def chat():
    data = request.json
    user_id = data[”user_id”]
    messages = load_session(user_id)
    messages.append({”role”: “user”, “content”: data[”message”]})

    response_text, messages = run_agent_turn(messages, SOUL)

    save_session(user_id, messages)
    return jsonify({”response”: response_text})

# Run the HTTP API in a background thread
threading.Thread(target=lambda: flask_app.run(port=5000), daemon=True).start()

# Telegram bot runs as before
app = Application.builder().token(os.getenv(”TELEGRAM_BOT_TOKEN”)).build()
app.add_handler(MessageHandler(filters.TEXT, handle_message))
app.run_polling()

Try it out: Tell the bot your name on Telegram. Then query via HTTP using the same user ID (your Telegram user ID) to prove the session is shared:

# Via Telegram
You: My name is Nader
Bot: Nice to meet you, Nader!

# Via HTTP — use your Telegram user ID so it hits the same session
curl -X POST http://127.0.0.1:5000/chat \
  -H “Content-Type: application/json” \
  -d ‘{”user_id”: “YOUR_TELEGRAM_USER_ID”, “message”: “What is my name?”}’

{”response”: “Your name is Nader!”}

Same agent, same sessions, same memory. Two different interfaces. That’s the gateway pattern.

The next step would be making this config-driven — a JSON file specifying which channels to start and how to authenticate them. That’s what OpenClaw does: its gateway manages Telegram, Discord, WhatsApp, Slack, Signal, iMessage, and more, all through a single config file. It also supports configurable session scoping — per-user, per-channel, or a single shared session — so the same person gets a unified experience across channels. We’ll keep our simple user-ID-as-session-key approach for now.

Goal: Context Compaction

Remember the growing session problem we flagged earlier? After chatting with your bot for weeks, the session file has thousands of messages. The total token count exceeds the model’s context window. Now what?

The fix: summarize old messages, keep recent ones. Add these two functions alongside your existing code:

def estimate_tokens(messages):
    “”“Rough token estimate: ~4 chars per token.”“”
    return sum(len(json.dumps(m)) for m in messages) // 4

def compact_session(user_id, messages):
    “”“Summarize old messages when context gets too long.”“”
    if estimate_tokens(messages) < 100_000:  # ~80% of a 128k window
        return messages  # No compaction needed

    split = len(messages) // 2
    old, recent = messages[:split], messages[split:]

    print(”  Compacting session history...”)

    summary = client.messages.create(
        model=”claude-sonnet-4-5-20250929”,
        max_tokens=2000,
        messages=[{
            “role”: “user”,
            “content”: (
                “Summarize this conversation concisely. Preserve:\n”
                “- Key facts about the user (name, preferences)\n”
                “- Important decisions made\n”
                “- Open tasks or TODOs\n\n”
                f”{json.dumps(old, indent=2)}”
            )
        }]
    )

    compacted = [{
        “role”: “user”,
        “content”: f”[Previous conversation summary]\n{summary.content[0].text}”
    }] + recent

    save_session(user_id, compacted)
    return compacted

Now add the compaction check at the top of handle_message, right after loading the session:

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)
    messages = load_session(user_id)
    messages = compact_session(user_id, messages)  # <-- add this line
    messages.append({”role”: “user”, “content”: update.message.text})

    response_text, messages = run_agent_turn(messages, SOUL)

    save_session(user_id, messages)
    await update.message.reply_text(response_text)

Try it out: To test compaction without chatting for hours, temporarily lower the threshold:

if estimate_tokens(messages) < 1000:  # lowered for testing

Have a conversation of 10-15 messages, then watch the old messages get replaced with a summary. The bot still remembers key facts, but the session file is much smaller.

OpenClaw’s compaction is more sophisticated — it splits messages into chunks by token count, summarizes each chunk separately, and includes a safety margin for estimation inaccuracy — but the core idea is identical.

Goal: Long-Term Memory

Session history gives you conversation memory. But what happens when you reset a session or start a new one? Everything is gone.

We need a separate memory system — persistent knowledge that survives session resets. The approach: give the agent tools to save and search memories stored as files.

Add these two tools to the TOOLS list:

{
    “name”: “save_memory”,
    “description”: “Save important information to long-term memory. Use for user preferences, key facts, and anything worth remembering across sessions.”,
    “input_schema”: {
        “type”: “object”,
        “properties”: {
            “key”: {
                “type”: “string”,
                “description”: “Short label, e.g. ‘user-preferences’, ‘project-notes’”
            },
            “content”: {
                “type”: “string”,
                “description”: “The information to remember”
            }
        },
        “required”: [”key”, “content”]
    }
},
{
    “name”: “memory_search”,
    “description”: “Search long-term memory for relevant information. Use at the start of conversations to recall context.”,
    “input_schema”: {
        “type”: “object”,
        “properties”: {
            “query”: {
                “type”: “string”,
                “description”: “What to search for”
            }
        },
        “required”: [”query”]
    }
}

Add their cases to execute_tool:

MEMORY_DIR = “./memory”

# Add these cases to execute_tool:

    elif name == “save_memory”:
        os.makedirs(MEMORY_DIR, exist_ok=True)
        filepath = os.path.join(MEMORY_DIR, f”{input[’key’]}.md”)
        with open(filepath, “w”) as f:
            f.write(input[”content”])
        return f”Saved to memory: {input[’key’]}”

    elif name == “memory_search”:
        query = input[”query”].lower()
        results = []
        if os.path.exists(MEMORY_DIR):
            for fname in os.listdir(MEMORY_DIR):
                if fname.endswith(”.md”):
                    with open(os.path.join(MEMORY_DIR, fname), “r”) as f:
                        content = f.read()
                    if any(word in content.lower() for word in query.split()):
                        results.append(f”--- {fname} ---\n{content}”)
        return “\n\n”.join(results) if results else “No matching memories found.”

Finally, update the SOUL so the agent knows about memory:

SOUL = “”“
# Who You Are
...existing personality...

## Memory
You have a long-term memory system.
- Use save_memory to store important information (user preferences, key facts, project details).
- Use memory_search at the start of conversations to recall context from previous sessions.
Memory files are stored in ./memory/ as markdown files.
“”“

Try it out:

You: Remember that my favorite restaurant is Elvies and I prefer to go on weekends.

Bot: [uses save_memory to write nader-profile.md]
     Got it — saved your restaurant preference.

[Reset the session or restart the bot]

You: Where should we go for dinner?

Bot: [uses memory_search for "restaurant dinner favorite"]
     How about Elvies? I know it's your favorite. Want to go this weekend?

The memory persists because it’s stored in files, not in the session. Reset the session, restart the bot — the memories are still there.

OpenClaw’s production memory uses vector search with embeddings for semantic matching (so “auth bug” matches “authentication issues”), but our keyword search works well for getting started.

Goal: Command Queue

Here’s a subtle but critical problem: what happens when two messages arrive at the same time?

Say you send “check my calendar” on Telegram and “what’s the weather” via the HTTP API simultaneously. Both try to load the same session, both try to append to it, and you get corrupted data.

The fix is simple: a per-session lock. Only one message processes at a time for each session. Different sessions can still run in parallel.

# Add to your bot
from collections import defaultdict

session_locks = defaultdict(threading.Lock)

Now wrap the body of handle_message with the lock:

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)

    with session_locks[user_id]:
        messages = load_session(user_id)
        messages = compact_session(user_id, messages)
        messages.append({”role”: “user”, “content”: update.message.text})

        response_text, messages = run_agent_turn(messages, SOUL)

        save_session(user_id, messages)

    await update.message.reply_text(response_text)

Do the same for the /chat HTTP endpoint:

@flask_app.route(”/chat”, methods=[”POST”])
def chat():
    data = request.json
    user_id = data[”user_id”]

    with session_locks[user_id]:
        messages = load_session(user_id)
        messages = compact_session(user_id, messages)
        messages.append({”role”: “user”, “content”: data[”message”]})

        response_text, messages = run_agent_turn(messages, SOUL)

        save_session(user_id, messages)

    return jsonify({”response”: response_text})

That’s it — five lines of setup. Messages for the same user queue up. Messages for different users run in parallel. No race conditions.

OpenClaw extends this with lane-based queues (separate lanes for messages, cron jobs, and sub-agents) so heartbeats never block real-time conversations.

Goal: Cron Jobs (Heartbeats)

So far our agent only responds when you talk to it. But what if you want it to check your email every morning? Or summarize your calendar before meetings?

You need scheduled execution. Let’s add heartbeats — recurring tasks that trigger the agent on a timer.

import schedule
import time

def setup_heartbeats():
    “”“Configure recurring agent tasks.”“”

    def morning_briefing():
        print(”\n⏰ Heartbeat: morning briefing”)
        # Use an isolated session key so cron doesn’t pollute main chat
        session_key = “cron:morning-briefing”

        with session_locks[session_key]:
            messages = load_session(session_key)
            messages.append({
                “role”: “user”,
                “content”: “Good morning! Check today’s date and give me a motivational quote.”
            })

            response_text, messages = run_agent_turn(messages, SOUL)
            save_session(session_key, messages)

        print(f”🤖 {response_text}\n”)
        # In production, you’d send this to Telegram/Discord too

    schedule.every().day.at(”07:30”).do(morning_briefing)

    # Run the scheduler in a background thread
    def scheduler_loop():
        while True:
            schedule.run_pending()
            time.sleep(60)

    threading.Thread(target=scheduler_loop, daemon=True).start()

# Call during startup, before run_polling()
setup_heartbeats()

The key insight: each heartbeat uses its own session key (cron:morning-briefing). This keeps scheduled tasks from cluttering your main conversation history. The heartbeat calls the same run_agent_turn function — it’s just another message, triggered by a timer instead of a human.

Try it out: For testing, change the schedule to run every minute:

schedule.every(1).minutes.do(morning_briefing)

You’ll see the heartbeat fire in your terminal, and the agent will respond. Change it back to a daily schedule when you’re done testing.

OpenClaw supports full cron expressions (30 7 * * *) and routes heartbeats through a separate command queue lane so they never block real-time messages.

Goal: Multi-Agent

One agent is useful. But as you add more tasks, you’ll find a single personality and toolset can’t cover everything well. A research assistant needs different instructions than a general assistant.

The fix: multiple agent configurations with routing. Each agent has its own SOUL, its own session, and you switch between them based on the message.

AGENTS = {
    “main”: {
        “name”: “Jarvis”,
        “soul”: SOUL,  # our existing SOUL
        “session_prefix”: “agent:main”,
    },
    “researcher”: {
        “name”: “Scout”,
        “soul”: “”“You are Scout, a research specialist.
Your job: find information and cite sources. Every claim needs evidence.
Use tools to gather data. Be thorough but concise.
Save important findings to memory for other agents to reference.”“”,
        “session_prefix”: “agent:researcher”,
    },
}

def resolve_agent(message_text):
    “”“Route messages to the right agent based on prefix commands.”“”
    if message_text.startswith(”/research “):
        return “researcher”, message_text[len(”/research “):]
    return “main”, message_text

Update handle_message to route messages to the right agent:

async def handle_message(update: Update, context):
    user_id = str(update.effective_user.id)
    agent_id, message_text = resolve_agent(update.message.text)
    agent = AGENTS[agent_id]
    session_key = f”{agent[’session_prefix’]}:{user_id}”

    with session_locks[session_key]:
        messages = load_session(session_key)
        messages = compact_session(session_key, messages)
        messages.append({”role”: “user”, “content”: message_text})

        response_text, messages = run_agent_turn(messages, agent[”soul”])

        save_session(session_key, messages)

    await update.message.reply_text(f”[{agent[’name’]}] {response_text}”)

Try it out:

You: What's the weather like?
[Jarvis] It's a nice day! I'd check a weather service for exact details.

You: /research What are the best practices for Python async programming?
[Scout] Here's what I found...
    [uses web_search, save_memory to gather and store findings]
    The key practices are: 1) Use asyncio.gather for concurrent tasks...

You: What did Scout find about Python async?
[Jarvis] [uses memory_search]
    Scout's research found that the key async best practices are...

Each agent has its own conversation history, but they share the same memory directory. Scout saves research findings; Jarvis can search for them later. They collaborate through shared files without needing direct messaging.

OpenClaw extends this with sub-agent spawning (a parent agent can spawn a child for a focused task) and inter-agent messaging, but the core pattern is the same: each agent is just a SOUL + session + tools.

Putting It All Together

Let’s combine everything we’ve built into a single runnable script. This is a clean standalone REPL that includes every feature from the tutorial: sessions, SOUL, tools, permissions, compaction, memory, command queue, cron, and multi-agent routing.

#!/usr/bin/env python3
# mini-openclaw.py - A minimal OpenClaw clone
# Run: uv run --with anthropic --with schedule python mini-openclaw.py

import anthropic
import subprocess
import json
import os
import re
import threading
import time
import schedule
from collections import defaultdict
from datetime import datetime

client = anthropic.Anthropic()

# ─── Configuration ───

WORKSPACE = os.path.expanduser(”~/.mini-openclaw”)
SESSIONS_DIR = os.path.join(WORKSPACE, “sessions”)
MEMORY_DIR = os.path.join(WORKSPACE, “memory”)
APPROVALS_FILE = os.path.join(WORKSPACE, “exec-approvals.json”)

# ─── Agents ───

AGENTS = {
    “main”: {
        “name”: “Jarvis”,
        “model”: “claude-sonnet-4-5-20250929”,
        “soul”: (
            “You are Jarvis, a personal AI assistant.\n”
            “Be genuinely helpful. Skip the pleasantries. Have opinions.\n”
            “You have tools — use them proactively.\n\n”
            “## Memory\n”
            f”Your workspace is {WORKSPACE}.\n”
            “Use save_memory to store important information across sessions.\n”
            “Use memory_search at the start of conversations to recall context.”
        ),
        “session_prefix”: “agent:main”,
    },
    “researcher”: {
        “name”: “Scout”,
        “model”: “claude-sonnet-4-5-20250929”,
        “soul”: (
            “You are Scout, a research specialist.\n”
            “Your job: find information and cite sources. Every claim needs evidence.\n”
            “Use tools to gather data. Be thorough but concise.\n”
            “Save important findings with save_memory for other agents to reference.”
        ),
        “session_prefix”: “agent:researcher”,
    },
}

# ─── Tools ───

TOOLS = [
    {
        “name”: “run_command”,
        “description”: “Run a shell command”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “command”: {”type”: “string”, “description”: “The command to run”}
            },
            “required”: [”command”]
        }
    },
    {
        “name”: “read_file”,
        “description”: “Read a file from the filesystem”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “path”: {”type”: “string”, “description”: “Path to the file”}
            },
            “required”: [”path”]
        }
    },
    {
        “name”: “write_file”,
        “description”: “Write content to a file (creates directories if needed)”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “path”: {”type”: “string”, “description”: “Path to the file”},
                “content”: {”type”: “string”, “description”: “Content to write”}
            },
            “required”: [”path”, “content”]
        }
    },
    {
        “name”: “save_memory”,
        “description”: “Save important information to long-term memory”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “key”: {”type”: “string”, “description”: “Short label (e.g. ‘user-preferences’)”},
                “content”: {”type”: “string”, “description”: “The information to remember”}
            },
            “required”: [”key”, “content”]
        }
    },
    {
        “name”: “memory_search”,
        “description”: “Search long-term memory for relevant information”,
        “input_schema”: {
            “type”: “object”,
            “properties”: {
                “query”: {”type”: “string”, “description”: “What to search for”}
            },
            “required”: [”query”]
        }
    },
]

# ─── Permission Controls ───

SAFE_COMMANDS = {”ls”, “cat”, “head”, “tail”, “wc”, “date”, “whoami”,
                 “echo”, “pwd”, “which”, “git”, “python”, “node”, “npm”}

def load_approvals():
    if os.path.exists(APPROVALS_FILE):
        with open(APPROVALS_FILE) as f:
            return json.load(f)
    return {”allowed”: [], “denied”: []}

def save_approval(command, approved):
    approvals = load_approvals()
    key = “allowed” if approved else “denied”
    if command not in approvals[key]:
        approvals[key].append(command)
    with open(APPROVALS_FILE, “w”) as f:
        json.dump(approvals, f, indent=2)

def check_command_safety(command):
    base_cmd = command.strip().split()[0] if command.strip() else “”
    if base_cmd in SAFE_COMMANDS:
        return “safe”
    approvals = load_approvals()
    if command in approvals[”allowed”]:
        return “approved”
    return “needs_approval”

# ─── Tool Execution ───

def execute_tool(name, tool_input):
    if name == “run_command”:
        cmd = tool_input[”command”]
        safety = check_command_safety(cmd)
        if safety == “needs_approval”:
            print(f”\n  ⚠️  Command: {cmd}”)
            confirm = input(”  Allow? (y/n): “).strip().lower()
            if confirm != “y”:
                save_approval(cmd, False)
                return “Permission denied by user.”
            save_approval(cmd, True)
        try:
            result = subprocess.run(
                cmd, shell=True, capture_output=True, text=True, timeout=30
            )
            output = result.stdout + result.stderr
            return output if output else “(no output)”
        except subprocess.TimeoutExpired:
            return “Command timed out after 30 seconds”
        except Exception as e:
            return f”Error: {e}”

    elif name == “read_file”:
        try:
            with open(tool_input[”path”], “r”) as f:
                return f.read()[:10000]
        except Exception as e:
            return f”Error: {e}”

    elif name == “write_file”:
        try:
            os.makedirs(os.path.dirname(tool_input[”path”]) or “.”, exist_ok=True)
            with open(tool_input[”path”], “w”) as f:
                f.write(tool_input[”content”])
            return f”Wrote to {tool_input[’path’]}”
        except Exception as e:
            return f”Error: {e}”

    elif name == “save_memory”:
        os.makedirs(MEMORY_DIR, exist_ok=True)
        filepath = os.path.join(MEMORY_DIR, f”{tool_input[’key’]}.md”)
        with open(filepath, “w”) as f:
            f.write(tool_input[”content”])
        return f”Saved to memory: {tool_input[’key’]}”

    elif name == “memory_search”:
        query = tool_input[”query”].lower()
        results = []
        if os.path.exists(MEMORY_DIR):
            for fname in os.listdir(MEMORY_DIR):
                if fname.endswith(”.md”):
                    with open(os.path.join(MEMORY_DIR, fname), “r”) as f:
                        content = f.read()
                    if any(w in content.lower() for w in query.split()):
                        results.append(f”--- {fname} ---\n{content}”)
        return “\n\n”.join(results) if results else “No matching memories found.”

    return f”Unknown tool: {name}”

# ─── Session Management ───

def get_session_path(session_key):
    os.makedirs(SESSIONS_DIR, exist_ok=True)
    safe_key = session_key.replace(”:”, “_”).replace(”/”, “_”)
    return os.path.join(SESSIONS_DIR, f”{safe_key}.jsonl”)

def load_session(session_key):
    path = get_session_path(session_key)
    messages = []
    if os.path.exists(path):
        with open(path, “r”) as f:
            for line in f:
                if line.strip():
                    try:
                        messages.append(json.loads(line))
                    except json.JSONDecodeError:
                        continue
    return messages

def append_message(session_key, message):
    with open(get_session_path(session_key), “a”) as f:
        f.write(json.dumps(message) + “\n”)

def save_session(session_key, messages):
    with open(get_session_path(session_key), “w”) as f:
        for msg in messages:
            f.write(json.dumps(msg) + “\n”)

# ─── Compaction ───

def estimate_tokens(messages):
    return sum(len(json.dumps(m)) for m in messages) // 4

def compact_session(session_key, messages):
    if estimate_tokens(messages) < 100_000:
        return messages
    split = len(messages) // 2
    old, recent = messages[:split], messages[split:]
    print(”\n  📦 Compacting session history...”)
    summary = client.messages.create(
        model=”claude-sonnet-4-5-20250929”,
        max_tokens=2000,
        messages=[{
            “role”: “user”,
            “content”: (
                “Summarize this conversation concisely. Preserve key facts, “
                “decisions, and open tasks:\n\n”
                f”{json.dumps(old, indent=2)}”
            )
        }]
    )
    compacted = [{
        “role”: “user”,
        “content”: f”[Conversation summary]\n{summary.content[0].text}”
    }] + recent
    save_session(session_key, compacted)
    return compacted

# ─── Command Queue ───

session_locks = defaultdict(threading.Lock)

# ─── Agent Loop ───

def serialize_content(content):
    serialized = []
    for block in content:
        if hasattr(block, “text”):
            serialized.append({”type”: “text”, “text”: block.text})
        elif block.type == “tool_use”:
            serialized.append({
                “type”: “tool_use”, “id”: block.id,
                “name”: block.name, “input”: block.input
            })
    return serialized

def run_agent_turn(session_key, user_text, agent_config):
    “”“Run a full agent turn: load session, call LLM in a loop, save.”“”
    with session_locks[session_key]:
        messages = load_session(session_key)
        messages = compact_session(session_key, messages)

        user_msg = {”role”: “user”, “content”: user_text}
        messages.append(user_msg)
        append_message(session_key, user_msg)

        for _ in range(20):  # max tool-use turns
            response = client.messages.create(
                model=agent_config[”model”],
                max_tokens=4096,
                system=agent_config[”soul”],
                tools=TOOLS,
                messages=messages
            )

            content = serialize_content(response.content)
            assistant_msg = {”role”: “assistant”, “content”: content}
            messages.append(assistant_msg)
            append_message(session_key, assistant_msg)

            if response.stop_reason == “end_turn”:
                return “”.join(
                    b.text for b in response.content if hasattr(b, “text”)
                )

            if response.stop_reason == “tool_use”:
                tool_results = []
                for block in response.content:
                    if block.type == “tool_use”:
                        print(f”  🔧 {block.name}: {json.dumps(block.input)[:100]}”)
                        result = execute_tool(block.name, block.input)
                        display = str(result)[:150]
                        print(f”     → {display}”)
                        tool_results.append({
                            “type”: “tool_result”,
                            “tool_use_id”: block.id,
                            “content”: str(result)
                        })

                results_msg = {”role”: “user”, “content”: tool_results}
                messages.append(results_msg)
                append_message(session_key, results_msg)

        return “(max turns reached)”

# ─── Multi-Agent Routing ───

def resolve_agent(message_text):
    “”“Route messages to the right agent based on prefix commands.”“”
    if message_text.startswith(”/research “):
        return “researcher”, message_text[len(”/research “):]
    return “main”, message_text

# ─── Cron / Heartbeats ───

def setup_heartbeats():
    def morning_check():
        print(”\n⏰ Heartbeat: morning check”)
        result = run_agent_turn(
            “cron:morning-check”,
            “Good morning! Check today’s date and give me a motivational quote.”,
            AGENTS[”main”]
        )
        print(f”🤖 {result}\n”)

    schedule.every().day.at(”07:30”).do(morning_check)

    def scheduler_loop():
        while True:
            schedule.run_pending()
            time.sleep(60)

    threading.Thread(target=scheduler_loop, daemon=True).start()

# ─── REPL ───

def main():
    for d in [WORKSPACE, SESSIONS_DIR, MEMORY_DIR]:
        os.makedirs(d, exist_ok=True)

    setup_heartbeats()

    session_key = “agent:main:repl”

    print(”Mini OpenClaw”)
    print(f”  Agents: {’, ‘.join(a[’name’] for a in AGENTS.values())}”)
    print(f”  Workspace: {WORKSPACE}”)
    print(”  Commands: /new (reset), /research <query>, /quit\n”)

    while True:
        try:
            user_input = input(”You: “).strip()
        except (EOFError, KeyboardInterrupt):
            print(”\nGoodbye!”)
            break

        if not user_input:
            continue
        if user_input.lower() in [”/quit”, “/exit”, “/q”]:
            print(”Goodbye!”)
            break
        if user_input.lower() == “/new”:
            session_key = f”agent:main:repl:{datetime.now().strftime(’%Y%m%d%H%M%S’)}”
            print(”  Session reset.\n”)
            continue

        agent_id, message_text = resolve_agent(user_input)
        agent_config = AGENTS[agent_id]
        sk = (
            f”{agent_config[’session_prefix’]}:repl”
            if agent_id != “main” else session_key
        )

        response = run_agent_turn(sk, message_text, agent_config)
        print(f”\n🤖 [{agent_config[’name’]}] {response}\n”)

if __name__ == “__main__”:
    main()

Save this as mini-openclaw.py and run it:

uv run --with anthropic --with schedule python mini-openclaw.py

Here’s what a session looks like:

Mini OpenClaw
  Agents: Jarvis, Scout
  Workspace: ~/.mini-openclaw
  Commands: /new (reset), /research <query>, /quit

You: Remember that my favorite restaurant is Hai Cenato and I prefer 7pm reservations

  🔧 save_memory: {"key": "user-preferences", "content": "Favorite restaurant...
     → Saved to memory: user-preferences

🤖 [Jarvis] Got it. Saved your restaurant preference - Hai Cenato, 7pm reservations.

You: What's in my project directory?

  🔧 run_command: {"command": "ls"}
     → src, package.json, README.md, node_modules, ...

🤖 [Jarvis] Your project has a standard Node.js structure with src/, package.json,
   and the usual suspects.

You: /new
  Session reset.

You: Where do I like to eat?

  🔧 memory_search: {"query": "restaurant favorite food"}
     → --- user-preferences.md ---
        Favorite restaurant: Hai Cenato...

🤖 [Jarvis] You like Hai Cenato, and you prefer 7pm reservations.

You: /research What are the latest trends in AI agents?

  🔧 web_search: {"query": "AI agent trends 2025"}
     → Search results for: AI agent trends 2025
  🔧 save_memory: {"key": "research-ai-agents", ...}
     → Saved to memory: research-ai-agents

🤖 [Scout] Here's what I found on current AI agent trends...

The memory persists across sessions. Agents collaborate through shared memory files. Commands require approval. Heartbeats run in the background. All in ~400 lines.

What We’ve Learned

Starting from a simple Telegram bot, we built every major component of a persistent AI assistant:

Persistent sessions (JSONL files): Crash-safe conversation memory. Each session is one file, each line is one message. Restart the process and everything is still there.

SOUL.md (system prompt): A personality file that transforms a generic AI into a specific agent with consistent behavior, boundaries, and style.

Tools + Agent loop: Structured tool definitions that let the AI decide when to act. The agent loop calls the LLM, executes any requested tools, feeds results back, and repeats until done.

Permission controls: An allowlist of safe commands plus persistent approvals, so dangerous operations require explicit consent.

The gateway pattern: One central agent with multiple interfaces. Telegram, HTTP, or any other channel - they all talk to the same sessions and the same memory.

Context compaction: When conversations outgrow the context window, summarize old messages and keep recent ones. The bot keeps its knowledge without hitting token limits.

Long-term memory: File-based storage with save and search tools. Knowledge that survives session resets, accessible to any agent.

Command queue: Per-session locking to prevent race conditions when multiple messages arrive simultaneously.

Heartbeats: Scheduled agent runs on a timer, each with its own isolated session. The agent wakes up, does its task, and goes back to sleep.

Multi-agent routing: Multiple agent configurations with different SOULs and session keys, routed by message content. Agents collaborate through shared memory files.

Each of these emerged from a practical problem:

• “The AI can’t remember anything” → Sessions

• “It responds like a generic chatbot” → SOUL.md

• “It can only talk, not act” → Tools + Agent loop

• “It runs dangerous commands without asking” → Permission controls

• “I want it on all my messaging apps” → Gateway

• “The conversation got too long” → Compaction

• “It forgets things between sessions” → Memory

• “Two messages at once corrupt the data” → Command queue

• “I want it to do things automatically” → Heartbeats

• “One agent can’t do everything well” → Multi-agent

This is how you could have invented OpenClaw.

Going Further

Our prototype covers the core architecture. Here’s how OpenClaw extends each idea for production use - features worth exploring once you’ve outgrown the basics.

Browser with Semantic Snapshots

Most AI assistants can’t see the web. OpenClaw gives the agent a browser via Playwright, but instead of sending screenshots (5MB each, expensive in tokens), it uses semantic snapshots - a text representation of the page’s accessibility tree:

# Simplified concept
snapshot = page.accessibility.snapshot()
# Output:
# - heading “Welcome to GitHub”
# - button “Sign In” [ref=1]
# - textbox “Email” [ref=2]
# - link “Forgot password?” [ref=3]

Each interactive element gets a numbered ref ID. When the agent wants to click something, it says “click ref=1” which maps to exactly one element on the page. No guessing, no “click the blue button near the top.” And since the snapshot is text instead of an image, it’s roughly 100x smaller than a screenshot, which means far fewer tokens per page.

Session Scoping & Identity Links

Our prototype uses user ID as the session key. OpenClaw supports configurable scoping:

• main (default): All DMs share one session - simple, great for single-user setups.

• per-peer: Each person gets one session across all channels.

• per-channel-peer: Each person per channel gets their own session.

Identity links let you merge sessions across channels for the same person, so Alice’s Telegram and Discord conversations share the same history.

Channel Plugin System

Our prototype hardcodes Telegram + HTTP. OpenClaw uses a plugin architecture where each channel (Telegram, Discord, WhatsApp, Slack, Signal, iMessage) is a separate adapter that normalizes messages into a common format. Adding a new channel means writing one adapter, not touching any agent logic.

Vector Memory Search

Our keyword search works, but misses semantic matches (”auth bug” won’t match “authentication issues”). OpenClaw’s production memory uses a hybrid approach: vector search via SQLite with embedding extensions for semantic similarity, plus FTS5 for exact keyword matches. Configurable embedding providers include OpenAI, local models, Gemini, and Voyage.

Sub-agent Spawning

Our multi-agent setup uses manual routing. OpenClaw lets agents spawn sub-agents programmatically - a parent agent calls sessions_spawn, the child runs in its own context with a timeout, and returns results to the parent. This enables patterns like “research this topic in depth” where the main agent delegates to a specialist and continues when it’s done.

Next Steps

If you want to build your own:

1. Start with one channel: get a Telegram or Discord bot working with sessions

2. Add tools incrementally: start with file read/write, then add shell execution

3. Add memory when you need it: once sessions reset, you’ll want persistent memory

4. Add channels when you outgrow one: the gateway pattern emerges naturally

5. Add agents when tasks specialize: don’t start with 10 agents, start with 2

Or just use OpenClaw. It’s open source and handles all the edge cases we glossed over. But now you know how it works under the hood.

That works well when one person is actively working with the code, but the session stays tied to that person’s laptop, local setup, open repo, and attention. Starting ten refactors means managing ten local workflows. A security fix across several repos still needs someone to clone the right projects, install dependencies, and keep the work moving.

Cloud agents move those sessions to remote infrastructure, where teams can run many sessions in parallel across any number of repos, each with the right dependencies, environment variables, and config already set up. They can start work from Slack, Jira, Linear, GitHub, an API, or a CLI, then review the PRs when they are ready. One person can start ten refactors, a security team can patch the same issue across multiple codebases, and CI can start a debugging session when a check fails, without tying the work to one laptop.

Everyone has a way to contribute. A senior engineer can start a session from the CLI. A PM can tag the agent in Slack. A junior developer can kick off a migration from a Jira ticket. A designer can report a bug and have a fix ready for review by end of day. And not every task needs a person to start it: a failed GitHub check can launch a debugging session on its own, and a weekly automation can ask Devin to update dependencies and open a PR.

This gives more people a way to request code changes. They don’t need to set up a local environment, use Git, or clone the repo (or even be able to), they just need to be able to describe the task clearly enough for the agent to attempt it and for an engineer to review the result.

I’ve been thinking about this since joining Cognition and watching how the team uses Devin internally. The useful patterns are not only about helping engineers write code faster, they come from giving the whole team access to an agent that can work across repos without depending on anyone’s laptop.

The core idea is simple: cloud agents are not just local agents running somewhere else, they are a different category, and the differences compound.

What a cloud agent actually is

A cloud agent runs on remote infrastructure. It has its own shell, IDE, and browser. It connects to your repos, CI, deployment pipeline, issue trackers, observability tools, and whatever else your team uses.

You communicate with it the way you would communicate with a remote engineer: send a task, let it work, then review the output.

The local agent model, like Cursor, Devin Local, or Claude Code in your terminal, is a human and an AI sharing one environment. You are pair programming.

The cloud agent model is delegation. You describe the task, the agent works independently, and you get back a PR.

These approaches are not mutually exclusive. They are complementary. Local agents make individual developers faster. Cloud agents open up the codebase to the rest of the organization, which matters a lot more as teams scale.

More people can request changes

At Cognition, non-engineers tag @Devin in Slack to fix documentation, report bugs, or request small features. They don’t need Git installed. They don’t need a local dev environment. They don’t need to know what a branch is.

Many small fixes get delayed because the person who finds the issue cannot make the change themselves. Someone notices a typo in the docs, a broken link, or a small product bug. Filing a ticket feels too heavy, and they do not have the tooling to open a PR. So the issue stays there.

A cloud agent removes that extra step. The person who finds the issue can tag the agent, describe the fix, and move on. The PR shows up. Someone reviews it. The work gets done.

One agent can work across repos

A local agent sees the repo a developer has open. A cloud agent can be configured for every repo in the org.

You can ask it questions about any codebase, start tasks in any repo, and let it handle the setup. An engineer on Team A can request a small fix in Team B’s repo without cloning it, installing dependencies, or stepping away from their current environment.

That matters for cross-team work. Small changes no longer require a full local setup just to get started.

Work can run in parallel

When you use a local agent, you are usually working with it in real time. You watch it work, approve edits, and correct it as it goes. That makes sense for architecture, complex debugging, and unclear requirements. Those tasks need someone with context making decisions.

A lot of engineering work does not need that level of attention. Targeted refactors, lint fixes, CVE remediation, test coverage, dependency upgrades, documentation updates, and migrations usually need clear instructions, tests, and review.

Cloud agents let you start those tasks without staying in the loop the whole time. You can describe ten tasks, start ten sessions, and come back to ten PRs. The limiting factor becomes review, tests, and merge decisions.

Events can start sessions

Sessions can start from events in the tools your team already uses.

A bug report lands in Slack, a CI check fails in GitHub, a Linear issue gets a bug label. A Sentry, Datadog, or PagerDuty alert hits a webhook. A weekly dependency update runs on a schedule.

Each event can start a new session with the relevant context attached. Conditions can filter when it runs, like only for a specific repo, only after a failed GitHub check, or only when a Linear issue has the right label.

The action can either start a new session, message an existing session, or send a notification. Cloud agents like Devin’s automation model supports triggers, conditions, and actions across Slack, GitHub, Linear, schedules, and webhooks.

That covers work that already starts from alerts, tickets, failed checks, support reports, and scheduled maintenance. When a check fails, an agent can investigate. When a vulnerability appears, an agent can open a fix PR. When a bug report lands in the right channel, an agent can triage it or start a repro.

Event-based workflows still need limits. Invocation caps, ACU budgets, filters, and permissions keep a noisy channel or repeated CI failure from creating too many sessions. With those controls in place, an event comes in, the agent gets the context, and the work starts.

Playbooks make repeated work easier

Once a team teaches the agent a workflow, other people can reuse it.

For example, a security engineer can write a Playbook for remediating vulnerabilities from SonarQube. After that, other teams can run the same workflow instead of asking the security engineer to repeat the same steps every time.

That is where cloud agents become more useful inside large companies. The value is not only one developer using one tool. The value is a shared agent that follows the company’s conventions, uses the right tools, respects permissions, and produces work the team can review.

Code Reviews

More agent sessions create more PRs. That increases review load.

The same cloud setup that runs coding agents can also run review agents. A review agent can group related diffs, detect moved code, catch obvious bugs, and answer questions about a change with codebase context.

Teams using cloud agents heavily need automated review. Without it, people either rubber-stamp PRs or spend too much time reviewing agent output.

Where the agent connects

A local agent connects to your filesystem and terminal. A cloud agent can connect to the tools your team already uses.

Slack and Teams can start tasks and send updates. Jira and Linear can provide ticket context. GitHub, GitLab, and Bitbucket can handle PRs and code review. Sentry, Datadog, and Vercel can provide logs for production debugging. Data warehouses can answer metrics questions without pulling an engineer into the request.

Because the agent runs in the cloud, these integrations can be configured once for the organization. Individual developers do not need to set them up on their own machines.

MCP makes this easier to extend. Connect Sentry, and the agent can inspect error logs. Connect a database, and someone on the team can ask a data question in Slack and get the SQL back with the answer, so they can check the logic.

What this means for pricing

Local agents are usually priced per seat because one developer uses the tool in their own workflow.

Cloud agents are usually priced by usage because tasks can come from many places. A PM can tag the agent in Slack. A Linear ticket can start a session. A CI failure can start a debugging task. Those requests do not map cleanly to one developer seat.

The unit of value is the work completed. That is why usage-based pricing makes more sense for cloud agents.

How teams get results

Deploying a cloud agent takes more than buying access. Teams get better results when they assign specific projects, write Playbooks, add Knowledge for repo conventions, track usage, and set permissions for different groups.

The best deployments start with high-ROI work: migrations, security remediation, flaky tests, dependency upgrades, documentation, and repetitive maintenance. Those tasks are easy to describe, easy to verify, and expensive to leave sitting in the backlog.

Some companies are reporting 5 to 6x faster migrations, 70 to 90 percent of security vulnerabilities handled automatically, and every PR reviewed by an agent. Those results come from giving the agent specific work and measuring the output.

Teams that only buy seats and wait for adoption usually get weaker results. Someone has to decide what work the agent should own, how people should use it, and how PRs should be reviewed.

Two ways to use coding agents

Use local agents when you want to sit with the code and make decisions while the edits happen (tight feedback loops)

Use cloud agents when the task is clear enough to run on its own and come back as a PR.

Both workflows matter. Local agents are useful for hands-on coding. Cloud agents are useful for maintenance work, cross-repo tasks, ticket-driven work, refactors, bugs, and requests from people who do not have a local dev environment.

The teams that use both have more options. They can keep developers in the loop when judgment matters and let agents handle the work that can be reviewed after the fact.

Cloud agents as shared engineering infrastructure

Cloud agents run in a separate environment, connect to team tools, accept tasks from multiple entry points, and return PRs.

They give engineers, PMs, designers, support, and other teams a way to request code work without setting up a local environment.

Local agents help developers while they are coding. Cloud agents help teams get work done when no one has the repo open.

At @cognition, we built Devin around this from the start.

Devin is available from Slack, CLI, API, Linear, and Jira. It is already deployed at organizations like Goldman Sachs, Citi, Ramp, Cal.com, Exa, and Eight Sleep.

Try Devin or reach out to see what this looks like across an engineering org.

Original X post here.

I’m excited to share that I’m joining Cognition, the team behind Devin, Windsurf, DeepWiki, and the recently launched Devin Review.

I’ve been building in the AI space since my days at AWS, but really became pilled when I launched my first viral AI app in February 2023.

After spending the holidays building with Opus 4.5 and Codex 5.2, it became clear we’d hit an inflection point. Conversations with friends and colleagues confirmed they were seeing it too.

We’re entering a world where the constraint on software development shifts from writing code to knowing what to build, architecting the solution, and orchestrating agents to execute it.

Thinking about the history of programming abstraction, we went from punch cards to assembly, assembly to C, C to Python. Each leap made software more accessible, and each time, doomsayers predicted the end of programming jobs. Instead, we got exponentially more software and exponentially more programmers.

AI coding tools are the next abstraction layer. And the companies that win won’t just have good models, they’ll have the right products, the right distribution, and the right understanding of how humans and AI should collaborate.

Why Cognition Got My Attention

There are a lot of impressive teams and products out there, and I spoke with several of them.

For me what stood out about Cognition was the combination - of team + momentum + products + strong PMF... and the relatively early stage vs TAM.

Devin has merged hundreds of thousands of pull requests in production codebases at companies like Goldman Sachs, Citi, Ramp, Cal.com, Exa, and Eight Sleep (too many household names to count).

Cognition has gone from 0 to $10B valuation in 2 years. ARR has 100x’ed in the past year. The company is ripping.

Here’s an example of how @cognition uses Devin internally. Anyone can tag Devin to work on any feature or bug, Devin will create the PR and even record a video demoing the update for us to review... including on the Windsurf codebase, which is 1M LOC and some of the most complex UI software in the world:

Devin executes the entire development lifecycle - writing, testing, and debugging code across multiple tasks in parallel - while Devin Review intelligently organizes complex diffs and catches bugs with precision to scale human code understanding without letting in AI slop.

Windsurf brings the same production-grade validation for synchronous workflows - hundreds of enterprise customers and hundreds of thousands of daily active users + a world-class engineering team shipping consistent improvements and polish with a clear long-term goal of making it the best development environment for agentic coding.

Cognition is an Agent Lab

Cognition is distinct from model labs in a crucial way: they’re product-first, model-last. Where model labs primarily research and sell models, agent labs primarily research and sell agents.

Everything Cognition builds is aimed at one goal: end-to-end software agents that ship production code.

They didn’t raise money to train a foundation model and then figure out the product. They built tools that solve real problems across the software development lifecycle, then invested in the model and infrastructure work needed to make those tools exceptional.

Different parts of the workflow demand different tools:

Devin: Your async engineering team that never sleeps. Migrate 500 repos. Knock out all new tickets. Fix every CVE. Generate tests across your entire codebase. @ Devin in Slack, move on to higher-leverage work, and come back to a completed PR.

Devin Review: As coding agents proliferate, code review - not code generation - becomes the bottleneck. Devin Review uses AI to intelligently organize complex diffs, detect bugs with precision, and provide codebase-aware explanations, scaling human understanding without letting in AI slop.

Windsurf: When you’re architecting a new system, making complex decisions, or working through ambiguous requirements, you want AI right there in your editor, collaborating with you in real-time. Tab completion, multi-file refactoring with Cascade, tight feedback loops.

DeepWiki: When you need to understand unfamiliar code - whether onboarding to a new project or navigating a massive legacy codebase - DeepWiki provides instant, accurate documentation and technical search, eliminating the friction of tribal knowledge gaps.

With more products coming soon.

Low Hype, Real Traction

The business fundamentals are remarkable, in fact it’s a little crazy that X/AI Twitter is so unaware of how things are growing.

The pricing model is usage-based (Agent Compute Units, not seats), which perfectly aligns with customer value - as teams use the tools more and get more results, they pay more.

This has enabled positive unit economics from the start while still funding accessible $20/month individual developer plans, so it’s sustainable for both sides.

It’s common to see 5-10x contract expansions mid-year - not at renewal, but proactively as teams roll out more broadly.

One banking customer went from $1.5M to over $15M in eight months, tracking their planned expansion from a pilot team to their full organization. There have since been more customers like this.

In addition to what I’ve outlined above, the team itself is remarkable. I’ll be working closely with @russelljkaplan @theodormarcu @itsandrewgao and many others. And yes, there are many IOI gold medalists.

I also get to work with @swyx again which I’m very excited about.

And the culture: intensely competitive, hard working, highly collaborative, obsessed with both technical excellence and enterprise polish.

Software Abundance

Software has always been more expensive than we can afford to build. There are entire categories of applications that don’t exist simply because the economics don’t work - the value delivered doesn’t justify the engineering cost.

AI coding tools change that equation. When migrations are 10x faster, when security fixes are 20x faster, when test coverage can jump 40 percentage points with minimal human effort, suddenly a lot more software becomes economically viable.

I’ve heard this called “Software Abundance,” and I think that’s right. We’re moving from a world constrained by how fast we can type code to a world constrained by how clearly we can specify what we want built.

That shift requires new tools, new skills, and new educational infrastructure. Cognition is building the tools. I’m here to help developers master the skills. I’ll be working on growth, education, developer experience, documentation, and awareness.

If you’re working with Devin or Windsurf, or if you’re just trying to figure out how to be more productive in this new agentic world, I’d love to hear from you. If you’d like to meet in person, I’ll be spending a lot more time in SF.

P.S. - If you have ideas for tutorials, frameworks, or educational content you’d like to see around AI-assisted development, drop me a note. I’m building the curriculum as we go.

P.P.S - We’re hiring

This is cross-posted from the original on x. You can also view it in full markdown here.

While many people use Claude Code daily, few realize that the core of what makes it powerful is surprisingly simple: it’s a loop that lets an AI read files, run commands, and iterate until a task is done.

The complexity comes from handling edge cases, building a good UX, and integrating with real development workflows.

In this post, I’ll start from scratch and build up to Claude Code’s architecture step by step, showing how you could have invented it yourself from first principles, using nothing but a terminal, an LLM API, and the desire to make AI actually useful.

End Goal: Making AI actually useful

First, let’s establish the problem we’re trying to solve.

When you use ChatGPT or Claude in a browser, you’re doing a lot of manual labor:

• Copy-paste code from the chat into files

• Run commands yourself, then copy errors back

• Provide context by uploading files or pasting content

• Manually iterate through the fix-test-debug cycle

You’re essentially acting as the AI’s hands. The AI thinks; you execute.

What if the AI could execute too?

Imagine telling an AI: “Fix the bug in auth.py“ and walking away. When you come back, the bug is fixed. The AI read the file, understood it, tried a fix, ran the tests, saw them fail, tried another approach, and eventually succeeded.

This is what an agent does. It’s an AI that can:

1. Take actions in the real world (read files, run commands)

2. Observe the results

3. Decide what to do next

4. Repeat until the task is complete

Let’s build one from scratch.

The Simplest Possible Agent

Let’s start with the absolute minimum: an AI that can run a single bash command.

#!/bin/bash
# agent-v0.sh - The simplest possible agent

PROMPT="$1"

# Ask Claude what command to run
RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "content-type: application/json" \
  -H "anthropic-version: 2023-06-01" \
  -d '{
    "model": "claude-opus-4-5-20251101",
    "max_tokens": 1024,
    "messages": [{"role": "user", "content": "'"$PROMPT"'\n\nRespond with ONLY a bash command. No markdown, no explanation, no code blocks."}]
  }')

# Extract the command from response
COMMAND=$(echo "$RESPONSE" | jq -r '.content[0].text')

echo "AI suggests: $COMMAND"
read -r -p "Run this command? (y/n) " CONFIRM

if [ "$CONFIRM" = "y" ]; then
  eval "$COMMAND"
fi

Usage

bash agent-v0.sh "list all Python files in this directory"
# AI suggests: ls *.py
# Run this command? (y/n)

This is... not very useful. The AI can suggest one command, then you’re back to doing everything manually.

But here’s the key insight: what if we put this in a loop?

Goal: Creating the agent loop

The fundamental insight behind all AI agents is the agent loop:

while (task not complete):
    1. AI decides what to do next
    2. Execute that action
    3. Show AI the result
    4. Go back to step 1

Let’s implement exactly this. The AI needs to tell us:

• What action to take

• Whether it’s done

We’ll use a simple JSON format:

#!/bin/bash
# agent-v1.sh - Agent with a loop

SYSTEM_PROMPT='You are a helpful assistant that can run bash commands.

When the user gives you a task, respond with JSON in this exact format:
{"action": "bash", "command": "your command here"}

When the task is complete, respond with:
{"action": "done", "message": "explanation of what was accomplished"}

Only respond with JSON. No other text.'

# We'll build messages as a JSON array (using jq for proper escaping)
MESSAGES="[]"

run_agent() {
    local USER_MSG="$1"
    
    # Add initial user message using jq to handle escaping
    MESSAGES=$(echo "$MESSAGES" | jq --arg msg "$USER_MSG" '. + [{"role": "user", "content": $msg}]')
    
    while true; do
        # Build the request body properly with jq
        REQUEST_BODY=$(jq -n \
            --arg model "claude-opus-4-5-20251101" \
            --arg system "$SYSTEM_PROMPT" \
            --argjson messages "$MESSAGES" \
            '{model: $model, max_tokens: 1024, system: $system, messages: $messages}')
        
        # Call the API
        RESPONSE=$(curl -s https://api.anthropic.com/v1/messages \
          -H "x-api-key: $ANTHROPIC_API_KEY" \
          -H "content-type: application/json" \
          -H "anthropic-version: 2023-06-01" \
          -d "$REQUEST_BODY")
        # Echo the response for debugging
        AI_TEXT=$(echo "$RESPONSE" | jq -r '.content[0].text')
        
        # Add assistant message to history
        MESSAGES=$(echo "$MESSAGES" | jq --arg msg "$AI_TEXT" '. + [{"role": "assistant", "content": $msg}]')
        
        # Parse the action from the JSON response
        ACTION=/__u/nader.substack.com/$(echo "$AI_TEXT" | jq -r '.action // empty')
        
        if [ -z "$ACTION" ]; then
            echo "❌ Could not parse response: $AI_TEXT"
            break
        elif [ "$ACTION" = "done" ]; then
            echo "✅ $(echo "$AI_TEXT" | jq -r '.message')"
            break
        elif [ "$ACTION" = "bash" ]; then
            COMMAND=$(echo "$AI_TEXT" | jq -r '.command')
            echo "🔧 Running: $COMMAND"
            
            # Execute and capture output
            OUTPUT=$(eval "$COMMAND" 2>&1)
            echo "$OUTPUT"
            
            # Feed result back to AI
            MESSAGES=$(echo "$MESSAGES" | jq --arg msg "Command output: $OUTPUT" '. + [{"role": "user", "content": $msg}]')
        else
            echo "❌ Unknown action: $ACTION"
            break
        fi
    done
}

run_agent "$1"

Now we have something that can actually iterate:

bash agent-v1.sh "Create a file called hello.py that prints hello world, then run it"

# 🔧 Running: echo 'print("hello world")' > hello.py
# 🔧 Running: python hello.py
# hello world
# ✅ Created hello.py and executed it successfully. It prints "hello world".

The AI ran two commands and then told us it was done. We’ve created an agent loop!

But wait! We’re executing arbitrary commands with no safety checks. The AI could rm -rf / and we’d blindly execute it.

Goal: Adding permission controls

Let’s add a human-in-the-loop for dangerous operations. First, we define a function that wraps command execution with a safety check:

# Add this function BEFORE run_agent() in your script
execute_with_permission() {
    local COMMAND="$1"
    
    # Check if command seems dangerous
    if echo "$COMMAND" | grep -qE 'rm |sudo |chmod |curl.*\|.*sh'; then
        # Use >&2 to print to stderr, so prompts display immediately
        # (stdout gets captured by the $(...) in the agent loop)
        echo "⚠️  Potentially dangerous command: $COMMAND" >&2
        echo "Allow? (y/n)" >&2
        read CONFIRM
        if [ "$CONFIRM" != "y" ]; then
            echo "DENIED BY USER"
            return 1
        fi
    fi
    
    eval "$COMMAND" 2>&1
}

Then, inside the agent loop, we replace the direct eval call with our new function:

        # BEFORE:
        OUTPUT=$(eval "$COMMAND" 2>&1)
        
        # AFTER (with permission check):
        OUTPUT=$(execute_with_permission "$COMMAND")

That’s it! The function sits between the AI’s request and actual execution, giving you a chance to block dangerous commands. When denied, you can feed that back to the AI so it can try a different approach.

Try it out:

# Create a test file
echo 'print("hello world")' > hello.py

# Ask the agent to delete it
bash agent-v1.sh "delete the file hello.py"

# 🔧 Running: rm hello.py
# ⚠️  Potentially dangerous command: rm hello.py
# Allow? (y/n)

Type y to allow the deletion, or n to block it.

This is the beginning of a permission system. Claude Code takes this much further with:

• Tool-specific permissions (file edits vs. bash commands)

• Pattern-based allowlists (Bash(npm test:*) allows any npm test command)

• Session-level “accept all” modes for when you trust the AI

The key insight: the human should be able to control what the AI can do, but with enough granularity that it’s not annoying.

Goal: Beyond bash - Adding tools

Running bash commands is powerful, but it’s also:

• Dangerous: unlimited access to the system

• Inefficient: reading a file shouldn’t spawn a subprocess

• Imprecise: output parsing is fragile

What if we gave the AI structured tools instead?

We’ll switch to Python here since it handles JSON and API calls more cleanly:

# agent-v2.py - Agent with structured tools
import anthropic
import json
import os

client = anthropic.Anthropic()

TOOLS = [
    {
        "name": "read_file",
        "description": "Read the contents of a file",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path to the file"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "write_file",
        "description": "Write content to a file",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path to the file"},
                "content": {"type": "string", "description": "Content to write"}
            },
            "required": ["path", "content"]
        }
    },
    {
        "name": "run_bash",
        "description": "Run a bash command",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"]
        }
    }
]

def execute_tool(name, input):
    """Execute a tool and return the result."""
    if name == "read_file":
        try:
            with open(input["path"], "r") as f:
                return f.read()
        except Exception as e:
            return f"Error: {e}"
    
    elif name == "write_file":
        try:
            with open(input["path"], "w") as f:
                f.write(input["content"])
            return f"Successfully wrote to {input['path']}"
        except Exception as e:
            return f"Error: {e}"
    
    elif name == "run_bash":
        import subprocess
        result = subprocess.run(
            input["command"], 
            shell=True, 
            capture_output=True, 
            text=True
        )
        return result.stdout + result.stderr

def run_agent(task):
    """Main agent loop."""
    messages = [{"role": "user", "content": task}]
    
    while True:
        response = client.messages.create(
            model="claude-opus-4-5-20251101",
            max_tokens=4096,
            tools=TOOLS,
            messages=messages
        )
        
        # Check if we're done
        if response.stop_reason == "end_turn":
            # Extract final text response
            for block in response.content:
                if hasattr(block, "text"):
                    print(f"✅ {block.text}")
            break
        
        # Process tool uses
        if response.stop_reason == "tool_use":
            # Add assistant's response to history
            messages.append({"role": "assistant", "content": response.content})
            
            tool_results = []
            for block in response.content:
                if block.type == "tool_use":
                    print(f"🔧 {block.name}: {json.dumps(block.input)}")
                    result = execute_tool(block.name, block.input)
                    print(f"   → {result[:200]}...")  # Truncate for display
                    
                    tool_results.append({
                        "type": "tool_result",
                        "tool_use_id": block.id,
                        "content": result
                    })
            
            # Add results to conversation
            messages.append({"role": "user", "content": tool_results})

if __name__ == "__main__":
    import sys
    run_agent(sys.argv[1])

Now we’re using Anthropic’s native tool use API. This is much better because:

1. Type safety: the AI knows exactly what parameters each tool accepts

2. Explicit actions: reading a file is a read_file call, not cat

3. Controlled surface area: we decide what tools exist

Try it out:

# Create a test file for the agent to work with
cat > main.py << 'EOF'
def calculate(x, y):
    return x + y

def greet(name):
    print(f"Hello, {name}!")
EOF

# Run the agent
uv run --with anthropic python agent-v2.py "Read main.py and add a docstring to the first function"

# 🔧 read_file: {"path": "main.py"}
#    → def calculate(x, y):...
# 🔧 write_file: {"path": "main.py", "content": "def calculate(x, y):\n    \"\"\"Calculate..."}
#    → Successfully wrote to main.py
# ✅ I've added a docstring to the calculate function explaining its purpose.

Goal: Making edits precise

Our write_file tool has a problem: it replaces the entire file. If the AI makes a small change to a 1000-line file, it has to output all 1000 lines. This is:

• Expensive: more output tokens = more cost

• Error-prone: the AI might accidentally drop lines

• Slow: generating that much text takes time

What if we had a tool for surgical edits?

{
    "name": "edit_file",
    "description": "Make a precise edit to a file by replacing a unique string",
    "input_schema": {
        "type": "object",
        "properties": {
            "path": {"type": "string"},
            "old_str": {"type": "string", "description": "Exact string to find (must be unique in file)"},
            "new_str": {"type": "string", "description": "String to replace it with"}
        },
        "required": ["path", "old_str", "new_str"]
    }
}

Implementation:

def edit_file(path, old_str, new_str):
    with open(path, "r") as f:
        content = f.read()
    
    # Ensure the string is unique
    count = content.count(old_str)
    if count == 0:
        return f"Error: '{old_str}' not found in file"
    if count > 1:
        return f"Error: '{old_str}' found {count} times. Must be unique."
    
    new_content = content.replace(old_str, new_str)
    with open(path, "w") as f:
        f.write(new_content)
    
    return f"Successfully replaced text in {path}"

This is exactly how Claude Code’s str_replace tool works. The requirement for uniqueness might seem annoying, but it’s actually a feature:

• Forces the AI to include enough context to be unambiguous

• Creates a natural diff that’s easy for humans to review

• Prevents accidental mass replacements

Goal: Searching the Codebase

So far our agent can read files it knows about. But what about a task like “find where the authentication bug is”?

The AI needs to search the codebase. Let’s add tools for that.

SEARCH_TOOLS = [
    {
        "name": "glob",
        "description": "Find files matching a pattern",
        "input_schema": {
            "type": "object",
            "properties": {
                "pattern": {"type": "string", "description": "Glob pattern (e.g., '**/*.py')"}
            },
            "required": ["pattern"]
        }
    },
    {
        "name": "grep",
        "description": "Search for a pattern in files",
        "input_schema": {
            "type": "object",
            "properties": {
                "pattern": {"type": "string", "description": "Regex pattern to search for"},
                "path": {"type": "string", "description": "Directory or file to search in"}
            },
            "required": ["pattern"]
        }
    }
]

Now the AI can:

1. glob(”**/*.py”) → find all Python files

2. grep(”def authenticate”, “src/”) → find authentication code

3. read_file(”src/auth.py”) → fead the relevant file

4. edit_file(...) → fix the bug

This is the pattern: give the AI tools to explore, and it can navigate codebases it’s never seen before.

Goal: Context management

Here’s a problem you’ll hit quickly: context windows are finite.

If you’re working on a large codebase, the conversation might look like:

• User: “Fix the bug in authentication”

• AI: reads 10 files, runs 20 commands, tries 3 approaches

• ...conversation is now 100,000 tokens

• AI: runs out of context and starts forgetting earlier information

How do we handle this?

Option 1: summarization (compaction)

When context gets too long, summarize what happened:

def compact_conversation(messages):
    """Summarize the conversation to free up context."""
    summary_prompt = """Summarize this conversation concisely, preserving:
    - The original task
    - Key findings and decisions
    - Current state of the work
    - What still needs to be done"""
    
    summary = client.messages.create(
        model="claude-opus-4-5-20251101",
        max_tokens=2000,
        messages=[
            {"role": "user", "content": f"{messages}\n\n{summary_prompt}"}
        ]
    )
    
    return [{"role": "user", "content": f"Previous work summary:\n{summary}"}]

Option 2: sub-agents (delegation)

For complex tasks, spawn a sub-agent with its own context:

def delegate_to_subagent(task, tools_allowed):
    """Spawn a sub-agent for a focused task."""
    result = run_agent(
        task=task,
        tools=tools_allowed,
        max_turns=10  # Prevent infinite loops
    )
    # Only return the result, not the full conversation
    return result.final_answer

This is why Claude Code has the concept of subagents: specialized agents that handle focused tasks in their own context, returning just the results.

Goal: the system prompt

We’ve been glossing over something important: how does the AI know how to behave?

The system prompt is where you encode:

• The AI’s identity and capabilities

• Guidelines for tool usage

• Project-specific context

• Behavioral rules

Here’s a simplified version of what makes Claude Code effective:

SYSTEM_PROMPT = """You are an AI assistant that helps with software development tasks.
You have access to the following tools:
- read_file: Read file contents
- write_file: Create or overwrite files
- edit_file: Make precise edits to existing files
- glob: Find files by pattern
- grep: Search for patterns in files
- bash: Run shell commands

## Guidelines

### Before making changes:
1. Understand the task fully before acting
2. Read relevant files to understand context
3. Plan your approach

### When editing code:
1. Use edit_file for small changes (preferred)
2. Use write_file only for new files or complete rewrites
3. Run tests after changes when possible
4. If tests fail, analyze the error and iterate

### General principles:
- Be concise but thorough
- Explain your reasoning briefly
- Ask for clarification if the task is ambiguous
- If you're stuck, say so instead of guessing

## Current Directory
You are working in: {current_directory}
"""

But here’s the problem: what if the project has specific conventions? What if the team uses a particular testing framework, or has a non-standard directory structure?

Goal: Project-Specific Context (CLAUDE.md)

Claude Code solves this with CLAUDE.md - a file at the project root that gets automatically included in context:

# CLAUDE.md

## Project Overview
This is a FastAPI application for user authentication.

## Key Commands
- `make test`: Run all tests
- `make lint`: Run linting
- `make dev`: Start development server

## Architecture
- `src/api/`: API routes
- `src/models/`: Database models
- `src/services/`: Business logic
- `tests/`: Test files (mirror src/ structure)

## Conventions
- All functions must have type hints
- Use pydantic for request/response models
- Write tests before implementing features (TDD)

## Known Issues
- The /auth/refresh endpoint has a race condition (see issue #142)

Now the AI knows:

• How to run tests for this project

• Where to find things

• What conventions to follow

• Known gotchas to watch out for

This is one of Claude Code’s most powerful features: project knowledge that travels with the code.

Putting it all together

Let’s see what we’ve built. The core of an AI coding agent is this loop:

1. Setup (runs once)

• Load the system prompt with tool descriptions, behavioral guidelines, and project context (CLAUDE.md)

• Initialize an empty conversation history

2. Agent Loop (repeats until done)

• Send conversation history to the LLM

• LLM decides: use a tool or respond to user

• If tool use:

• Check permissions (prompt user if dangerous)

• Execute the tool (read_file, edit_file, bash, glob, grep, etc.)

• Add the result to conversation history

• Loop back to step 2

• If final answer:

  • Display response to user

  • Done

That’s it. Every AI coding agent, from our 50-line bash script to Claude Code, follows this pattern.

Now let’s build a complete, working mini-Claude Code that you can actually use. It combines everything we’ve learned: the agent loop, structured tools, permission checks, and an interactive REPL:

#!/usr/bin/env python3
# mini-claude-code.py - A minimal Claude Code clone

import anthropic
import subprocess
import os
import json

client = anthropic.Anthropic()

TOOLS = [
    {
        "name": "read_file",
        "description": "Read the contents of a file",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path to the file"}
            },
            "required": ["path"]
        }
    },
    {
        "name": "write_file",
        "description": "Write content to a file (creates or overwrites)",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Path to the file"},
                "content": {"type": "string", "description": "Content to write"}
            },
            "required": ["path", "content"]
        }
    },
    {
        "name": "list_files",
        "description": "List files in a directory",
        "input_schema": {
            "type": "object",
            "properties": {
                "path": {"type": "string", "description": "Directory path (default: current directory)"}
            }
        }
    },
    {
        "name": "run_command",
        "description": "Run a shell command",
        "input_schema": {
            "type": "object",
            "properties": {
                "command": {"type": "string", "description": "The command to run"}
            },
            "required": ["command"]
        }
    }
]

DANGEROUS_PATTERNS = ["rm ", "sudo ", "chmod ", "mv ", "cp ", "> ", ">>"]

def check_permission(tool_name, tool_input):
    """Check if an action requires user permission."""
    if tool_name == "run_command":
        cmd = tool_input.get("command", "")
        if any(p in cmd for p in DANGEROUS_PATTERNS):
            print(f"\n⚠️  Potentially dangerous command: {cmd}")
            response = input("Allow? (y/n): ").strip().lower()
            return response == "y"
    elif tool_name == "write_file":
        path = tool_input.get("path", "")
        print(f"\n📝 Will write to: {path}")
        response = input("Allow? (y/n): ").strip().lower()
        return response == "y"
    return True

def execute_tool(name, tool_input):
    """Execute a tool and return the result."""
    if name == "read_file":
        path = tool_input["path"]
        try:
            with open(path, "r") as f:
                content = f.read()
            return f"Contents of {path}:\n{content}"
        except Exception as e:
            return f"Error reading file: {e}"

    elif name == "write_file":
        path = tool_input["path"]
        content = tool_input["content"]
        try:
            with open(path, "w") as f:
                f.write(content)
            return f"✅ Successfully wrote to {path}"
        except Exception as e:
            return f"Error writing file: {e}"

    elif name == "list_files":
        path = tool_input.get("path", ".")
        try:
            files = os.listdir(path)
            return f"Files in {path}:\n" + "\n".join(f"  {f}" for f in sorted(files))
        except Exception as e:
            return f"Error listing files: {e}"

    elif name == "run_command":
        cmd = tool_input["command"]
        try:
            result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=30)
            output = result.stdout + result.stderr
            return f"$ {cmd}\n{output}" if output else f"$ {cmd}\n(no output)"
        except subprocess.TimeoutExpired:
            return f"Command timed out after 30 seconds"
        except Exception as e:
            return f"Error running command: {e}"

    return f"Unknown tool: {name}"

def agent_loop(user_message, conversation_history):
    """Run the agent loop until the task is complete."""
    conversation_history.append({"role": "user", "content": user_message})

    while True:
        # Call Claude
        response = client.messages.create(
            model="claude-opus-4-5-20251101",
            max_tokens=4096,
            system=f"You are a helpful coding assistant. Working directory: {os.getcwd()}",
            tools=TOOLS,
            messages=conversation_history
        )

        # Add assistant response to history
        conversation_history.append({"role": "assistant", "content": response.content})

        # Check if we're done (no tool use)
        if response.stop_reason == "end_turn":
            # Print the final text response
            for block in response.content:
                if hasattr(block, "text"):
                    print(f"\n🤖 {block.text}")
            break

        # Process tool calls
        tool_results = []
        for block in response.content:
            if block.type == "tool_use":
                tool_name = block.name
                tool_input = block.input

                print(f"\n🔧 {tool_name}: {json.dumps(tool_input)}")

                # Check permissions
                if not check_permission(tool_name, tool_input):
                    result = "Permission denied by user"
                    print(f"   🚫 {result}")
                else:
                    result = execute_tool(tool_name, tool_input)
                    # Truncate long output for display
                    display = result[:200] + "..." if len(result) > 200 else result
                    print(f"   → {display}")

                tool_results.append({
                    "type": "tool_result",
                    "tool_use_id": block.id,
                    "content": result
                })

        # Add tool results to conversation
        conversation_history.append({"role": "user", "content": tool_results})

    return conversation_history

def main():
    print("Mini Claude Code")
    print(" Type your requests, or 'quit' to exit.\n")

    conversation_history = []

    while True:
        try:
            user_input = input("You: ").strip()
        except (EOFError, KeyboardInterrupt):
            print("\nGoodbye!")
            break

        if not user_input:
            continue
        if user_input.lower() in ["quit", "exit", "q"]:
            print("Goodbye!")
            break

        conversation_history = agent_loop(user_input, conversation_history)

if __name__ == "__main__":
    main()

Save this as mini-claude-code.py and run it:

uv run --with anthropic python mini-claude-code.py

Here’s what a session looks like:

Mini Claude Code
 Type your requests, or 'quit' to exit.

You: create a python file that prints the fibonacci sequence up to n

🔧 write_file: {"path": "fibonacci.py", "content": "def fibonacci(n):\n    ..."}

📝 Will write to: fibonacci.py
Allow? (y/n): y
   → ✅ Successfully wrote to fibonacci.py

🤖 I've created fibonacci.py with a function that prints the Fibonacci sequence.
   Would you like me to run it to test it?

You: yes, run it with n=10

🔧 run_command: {"command": "python fibonacci.py 10"}
   → $ python fibonacci.py 10
     0 1 1 2 3 5 8 13 21 34

🤖 The script works correctly! It printed the first 10 Fibonacci numbers.

You: quit
Goodbye!

That’s a working mini Claude Code clone in ~150 lines. It has:

• Interactive REPL: keeps conversation context between prompts

• Multiple tools: read, write, list files, run commands

• Permission checks: asks before writing files or running dangerous commands

• Conversation memory: each follow-up builds on previous context

This is essentially what Claude Code does, plus:

• A polished terminal UI

• Sophisticated permission system

• Context compaction when conversations get long

• Subagent delegation for complex tasks

• Hooks for custom automation

• Integration with git and other dev tools

The Claude Agent SDK

If you want to build on this foundation without reinventing the wheel, Anthropic offers the Claude Agent SDK. It’s the same engine that powers Claude Code, exposed as a library.

Here’s what our simple agent looks like using the SDK:

import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Fix the bug in auth.py",
  options: {
    model: "claude-opus-4-5-20251101",
    allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"],
    maxTurns: 50
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text);
      } else if ("name" in block) {
        console.log(`Using tool: ${block.name}`);
      }
    }
  }
}

The SDK handles:

• The agent loop (so you don’t have to)

• All the built-in tools (Read, Write, Edit, Bash, Glob, Grep, etc.)

• Permission management

• Context tracking

• Sub-agent coordination

What We’ve Learned

Starting from a simple bash script, we discovered:

1. The agent loop: AI decides → execute → observe → repeat

2. Structured tools: better than raw bash for safety and precision

3. Surgical edits: str_replace beats full file rewrites

4. Search tools: let the AI explore codebases

5. Context management: compaction and delegation handle long tasks

6. Project knowledge:

   CLAUDE.md

   gives project-specific context

Each of these emerged from a practical problem:

• “How do I make the AI do more than one thing?” → agent loop

• “How do I prevent it from destroying my system?” → permission system

• “How do I make edits efficient?” → str_replace tool

• “How does it find code it doesn’t know about?” → search tools

• “What happens when context runs out?” → compaction

• “How does it know my project’s conventions?” →

  CLAUDE.md

This is how you could have invented Claude Code. The core ideas are simple.

The complexity comes from handling edge cases, building a good UX, and integrating with real development workflows.

Next Steps

If you want to build your own agents:

1. Start simple: a basic agent loop with 2-3 tools

2. Add tools incrementally: each new capability should solve a real problem

3. Handle errors gracefully: tools fail; your agent should recover

4. Test on real tasks: the edge cases will teach you what’s missing

5. Consider using the Claude Agent SDK: why reinvent the wheel?

The future of software development is agents that can actually do things. Now we know how they work!

Resources:

• Claude Agent SDK Documentation

• Claude Code Documentation

• Anthropic API Reference

This is cross-posted from this post on x. You can also view it in markdown in it’s entirety here.

If you’ve used Claude Code, you’ve seen what an AI agent can actually do: read files, run commands, edit code, figure out the steps to accomplish a task.

And you know it doesn’t just help you write code, it takes ownership of problems and works through them the way a thoughtful engineer would.

The Claude Agent SDK is the same engine, yours to point at whatever problem you want, so you can easily build agents of your own.

It’s the infrastructure behind Claude Code, exposed as a library. You get the agent loop, the built-in tools, the context management, basically everything you’d otherwise have to build yourself.

This guide walks through building a code review agent from scratch. By the end, you’ll have something that can analyze a codebase, find bugs and security issues, and return structured feedback.

More importantly, you’ll understand how the SDK works so you can build whatever you actually need.

What we’re building

Our code review agent will:

1. Analyze a codebase for bugs and security issues

2. Read files and search through code autonomously

3. Provide structured, actionable feedback

4. Track its progress as it works

The stack

• Runtime - Claude Code CLI
• SDK - @anthropic-ai/claude-agent-sdk
• Language - TypeScript
• Model - Claude Opus 4.5

What the SDK gives you

If you’ve built agents with the raw API, you know the pattern: call the model, check if it wants to use a tool, execute the tool, feed the result back, repeat until done. This can get tedious when building anything non-trivial.

The SDK handles that loop:

// Without the SDK: You manage the loop
let response = await client.messages.create({...});
while (response.stop_reason === "tool_use") {
  const result = yourToolExecutor(response.tool_use);
  response = await client.messages.create({ tool_result: result, ... });
}

// With the SDK: Claude manages it
for await (const message of query({ prompt: "Fix the bug in auth.py" })) {
  console.log(message); // Claude reads files, finds bugs, edits code
}

You also get working tools out of the box:

• Read - read any file in the working directory
• Write - create new files
• Edit - make precise edits to existing files
• Bash - run terminal commands
• Glob- find files by pattern
• Grep - search file contents with regex
• WebSearch - search the web
• WebFetch - fetch and parse web pages

You don’t have to implement any of this yourself.

Prerequisites

1. Node.js 18+ installed

2. An Anthropic API key (get one here)

Getting started

Step 1: Install Claude Code CLI

The Agent SDK uses Claude Code as its runtime:

npm install -g @anthropic-ai/claude-code

After installing, run claude in your terminal and follow the prompts to authenticate.

Step 2: Create your project

mkdir code-review-agent && cd code-review-agent
npm init -y
npm install @anthropic-ai/claude-agent-sdk
npm install -D typescript @types/node tsx

Step 3: Set your API key

export ANTHROPIC_API_KEY=your-api-key

Your first agent

Create agent.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "What files are in this directory?",
    options: {
      model: "opus",
      allowedTools: ["Glob", "Read"],
      maxTurns: 250
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        }
      }
    }
    
    if (message.type === "result") {
      console.log("\nDone:", message.subtype);
    }
  }
}

main();

Run it:

npx tsx agent.ts

Claude will use the Glob tool to list files and tell you what it found.

Understanding the message stream

The query() function returns an async generator that streams messages as Claude works. Here are the key message types:

for await (const message of query({ prompt: "..." })) {
  switch (message.type) {
    case "system":
      // Session initialization info
      if (message.subtype === "init") {
        console.log("Session ID:", message.session_id);
        console.log("Available tools:", message.tools);
      }
      break;
      
    case "assistant":
      // Claude's responses and tool calls
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log("Claude:", block.text);
        } else if ("name" in block) {
          console.log("Tool call:", block.name);
        }
      }
      break;
      
    case "result":
      // Final result
      console.log("Status:", message.subtype); // "success" or error type
      console.log("Cost:", message.total_cost_usd);
      break;
  }
}

Building a code review agent

Now let’s build something useful. Create review-agent.ts:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function reviewCode(directory: string) {
  console.log(`\n🔍 Starting code review for: ${directory}\n`);
  
  for await (const message of query({
    prompt: `Review the code in ${directory} for:
1. Bugs and potential crashes
2. Security vulnerabilities  
3. Performance issues
4. Code quality improvements

Be specific about file names and line numbers.`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions", // Auto-approve read operations
      maxTurns: 250
    }
  })) {
    // Show Claude's analysis as it happens
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        } else if ("name" in block) {
          console.log(`\n📁 Using ${block.name}...`);
        }
      }
    }
    
    // Show completion status
    if (message.type === "result") {
      if (message.subtype === "success") {
        console.log(`\n✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}`);
      } else {
        console.log(`\n❌ Review failed: ${message.subtype}`);
      }
    }
  }
}

// Review the current directory
reviewCode(".");

Testing It Out

Create a file with some intentional issues. Create example.ts:

function processUsers(users: any) {
  for (let i = 0; i <= users.length; i++) { // Off-by-one error
    console.log(users[i].name.toUpperCase()); // No null check
  }
}

function connectToDb(password: string) {
  const connectionString = `postgres://admin:${password}@localhost/db`;
  console.log("Connecting with:", connectionString); // Logging sensitive data
}

async function fetchData(url) { // Missing type annotation
  const response = await fetch(url);
  return response.json(); // No error handling
}

Run the review:

bash

npx tsx review-agent.ts

Claude will identify the bugs, security issues, and suggest fixes.

Adding Structured Output

For programmatic use, you’ll want structured data. The SDK supports JSON Schema output:

import { query } from "@anthropic-ai/claude-agent-sdk";

const reviewSchema = {
  type: "object",
  properties: {
    issues: {
      type: "array",
      items: {
        type: "object",
        properties: {
          severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
          category: { type: "string", enum: ["bug", "security", "performance", "style"] },
          file: { type: "string" },
          line: { type: "number" },
          description: { type: "string" },
          suggestion: { type: "string" }
        },
        required: ["severity", "category", "file", "description"]
      }
    },
    summary: { type: "string" },
    overallScore: { type: "number" }
  },
  required: ["issues", "summary", "overallScore"]
};

async function reviewCodeStructured(directory: string) {
  for await (const message of query({
    prompt: `Review the code in ${directory}. Identify all issues.`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      outputFormat: {
        type: "json_schema",
        schema: reviewSchema
      }
    }
  })) {
    if (message.type === "result" && message.subtype === "success") {
      const review = message.structured_output as {
        issues: Array<{
          severity: string;
          category: string;
          file: string;
          line?: number;
          description: string;
          suggestion?: string;
        }>;
        summary: string;
        overallScore: number;
      };
      
      console.log(`\n📊 Code Review Results\n`);
      console.log(`Score: ${review.overallScore}/100`);
      console.log(`Summary: ${review.summary}\n`);
      
      for (const issue of review.issues) {
        const icon=/__u/nader.substack.com/issue.severity === "critical" ? "🔴" :
                     issue.severity === "high" ? "🟠" :
                     issue.severity === "medium" ? "🟡" : "🟢";
        console.log(`${icon} [${issue.category.toUpperCase()}] ${issue.file}${issue.line ? `:${issue.line}` : ""}`);
        console.log(`   ${issue.description}`);
        if (issue.suggestion) {
          console.log(`   💡 ${issue.suggestion}`);
        }
        console.log();
      }
    }
  }
}

reviewCodeStructured(".");

Handling permissions

By default, the SDK asks for approval before executing tools. You can customize this:

Permission modes

options: {
  // Standard mode - prompts for approval
  permissionMode: "default",
  
  // Auto-approve file edits
  permissionMode: "acceptEdits",
  
  // No prompts (use with caution)
  permissionMode: "bypassPermissions"
}

Custom permission handler

For fine-grained control, use canUseTool:

options: {
  canUseTool: async (toolName, input) => {
    // Allow all read operations
    if (["Read", "Glob", "Grep"].includes(toolName)) {
      return { behavior: "allow", updatedInput: input };
    }
    
    // Block writes to certain files
    if (toolName === "Write" && input.file_path?.includes(".env")) {
      return { behavior: "deny", message: "Cannot modify .env files" };
    }
    
    // Allow everything else
    return { behavior: "allow", updatedInput: input };
  }
}

Creating subagents

For complex tasks, you can create specialized subagents:

import { query, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

async function comprehensiveReview(directory: string) {
  for await (const message of query({
    prompt: `Perform a comprehensive code review of ${directory}. 
Use the security-reviewer for security issues and test-analyzer for test coverage.`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep", "Task"], // Task enables subagents
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      agents: {
        "security-reviewer": {
          description: "Security specialist for vulnerability detection",
          prompt: `You are a security expert. Focus on:
- SQL injection, XSS, CSRF vulnerabilities
- Exposed credentials and secrets
- Insecure data handling
- Authentication/authorization issues`,
          tools: ["Read", "Grep", "Glob"],
          model: "sonnet"
        } as AgentDefinition,
        
        "test-analyzer": {
          description: "Test coverage and quality analyzer",
          prompt: `You are a testing expert. Analyze:
- Test coverage gaps
- Missing edge cases
- Test quality and reliability
- Suggestions for additional tests`,
          tools: ["Read", "Grep", "Glob"],
          model: "haiku" // Use faster model for simpler analysis
        } as AgentDefinition
      }
    }
  })) {
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("text" in block) {
          console.log(block.text);
        } else if ("name" in block && block.name === "Task") {
          console.log(`\n🤖 Delegating to: ${(block.input as any).subagent_type}`);
        }
      }
    }
  }
}

comprehensiveReview(".");

Session management

For multi-turn conversations, capture and resume sessions:

import { query } from "@anthropic-ai/claude-agent-sdk";

async function interactiveReview() {
  let sessionId: string | undefined;
  
  // Initial review
  for await (const message of query({
    prompt: "Review this codebase and identify the top 3 issues",
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep"],
      permissionMode: "bypassPermissions",
      maxTurns: 250
    }
  })) {
    if (message.type === "system" && message.subtype === "init") {
      sessionId = message.session_id;
    }
    // ... handle messages
  }
  
  // Follow-up question using same session
  if (sessionId) {
    for await (const message of query({
      prompt: "Now show me how to fix the most critical issue",
      options: {
        resume: sessionId, // Continue the conversation
        allowedTools: ["Read", "Glob", "Grep"],
        maxTurns: 250
      }
    })) {
      // Claude remembers the previous context
    }
  }
}

Using hooks

Hooks let you intercept and customize agent behavior:

import { query, HookCallback, PreToolUseHookInput } from "@anthropic-ai/claude-agent-sdk";

// Hook callbacks receive three arguments:
// 1. input - details about the event (tool name, arguments, etc.)
// 2. toolUseId - correlates PreToolUse and PostToolUse events for the same call
// 3. context - contains AbortSignal for cancellation
const auditLogger: HookCallback = async (input, toolUseId, { signal }) => {
  if (input.hook_event_name === "PreToolUse") {
    const preInput = input as PreToolUseHookInput;
    console.log(`[AUDIT] ${new Date().toISOString()} - ${preInput.tool_name}`);
  }
  return {}; // Return empty object to allow the operation
};

const blockDangerousCommands: HookCallback = async (input, toolUseId, { signal }) => {
  if (input.hook_event_name === "PreToolUse") {
    const preInput = input as PreToolUseHookInput;
    if (preInput.tool_name === "Bash") {
      const command = (preInput.tool_input as any).command || "";
      if (command.includes("rm -rf") || command.includes("sudo")) {
        return {
          hookSpecificOutput: {
            hookEventName: "PreToolUse",
            permissionDecision: "deny",  // Block the tool from executing
            permissionDecisionReason: "Dangerous command blocked"
          }
        };
      }
    }
  }
  return {};
};

for await (const message of query({
  prompt: "Clean up temporary files",
  options: {
    model: "opus",
    allowedTools: ["Bash", "Glob"],
    maxTurns: 50,
    hooks: {
      // PreToolUse fires before each tool executes
      // Other hooks: PostToolUse, Stop, SessionStart, SessionEnd, etc.
      PreToolUse: [
        // Each entry has an optional matcher (regex) and an array of callbacks
        // No matcher = runs for ALL tool calls
        { hooks: [auditLogger] },
        
        // matcher: 'Bash' = only runs when tool_name matches 'Bash'
        // Use regex for multiple tools: 'Bash|Write|Edit'
        { matcher: "Bash", hooks: [blockDangerousCommands] }
      ]
    }
  }
})) {
  if (message.type === "assistant") {
    for (const block of message.message.content) {
      if ("text" in block) {
        console.log(block.text);
      }
    }
  }
}

Custom tool calling

Tools are how agents interact with the world - reading files, calling APIs, querying databases, running code. The SDK includes built-in tools for common operations (filesystem, shell, web), but most agents will need custom tools to access your own systems.

The raw API pattern

Without the SDK, you manage the tool loop yourself:

// 1. Define tools with their schemas
const tools = [{
  name: "get_weather",
  description: "Get current weather for a city",
  input_schema: {
    type: "object",
    properties: {
      city: { type: "string", description: "City name" }
    },
    required: ["city"]
  }
}];

// 2. Write an executor for each tool
function executeTool(name: string, input: any): string {
  if (name === "get_weather") {
    return fetchWeatherAPI(input.city);
  }
  throw new Error(`Unknown tool: ${name}`);
}

// 3. Run the agent loop
const messages = [{ role: "user", content: "What's the weather in Tokyo?" }];

let response = await client.messages.create({
  model: "claude-opus-4-5-20251101",
  tools,
  messages
});

while (response.stop_reason === "tool_use") {
  messages.push({ role: "assistant", content: response.content });
  
  const toolResults = response.content
    .filter(block => block.type === "tool_use")
    .map(toolUse => ({
      type: "tool_result",
      tool_use_id: toolUse.id,
      content: executeTool(toolUse.name, toolUse.input)
    }));
  
  messages.push({ role: "user", content: toolResults });
  response = await client.messages.create({ model, tools, messages });
}

const textBlock = response.content.find(block => block.type === "text");
if (textBlock && textBlock.type === "text") {
  console.log("Final response:", textBlock.text);
}

Key points:

• Claude decides when to use tools based on the user’s request and tool descriptions

• You execute the tools and return results

• The loop continues until Claude has enough information (stop_reason: "end_turn")

• Message history grows with each iteration - the API is stateless, so every request needs the full conversation

What the SDK handles

When you use built-in tools like allowedTools: ["Read", "Glob"], the SDK manages all of this automatically - definitions, execution, and the loop.

For custom tools, you need a way to define them so the SDK can do the same. That’s what MCP provides.

Adding custom tools with MCP

Extend Claude with custom tools using Model Context Protocol:

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

// Create your custom MCP server
const customServer = createSdkMcpServer({
  name: "code-metrics",
  version: "1.0.0",
  tools: [
    // Define a custom tool using the `tool` helper
    // Arguments: name, description, input schema, handler function
    tool(
      "analyze_complexity",
      "Calculate cyclomatic complexity for a file",
      {
        // Zod schema defines what inputs the tool accepts
        filePath: z.string().describe("Path to the file to analyze")
      },
      // Handler function - runs when Claude calls the tool
      async (args) => {
        // In real implementation, calculate actual complexity 
        const complexity = Math.floor(Math.random() * 20) + 1;
        
        // Return format required by MCP - array of content blocks
        return {
          content: [{
            type: "text",
            text: `Cyclomatic complexity for ${args.filePath}: ${complexity}`
          }]
        };
      }
    )
  ]
});

async function analyzeCode(filePath: string) {
  for await (const message of query({
    prompt: `Analyze the complexity of ${filePath}`,
    options: {
      model: "opus",
      
      // Register the custom MCP server
      // The key ("code-metrics") becomes part of the tool name
      mcpServers: {
        "code-metrics": customServer
      },
      
      // Specify which tools Claude can use
      // MCP tools follow the pattern: mcp__<server-name>__<tool-name>
      allowedTools: ["Read", "mcp__code-metrics__analyze_complexity"],
      
      // Maximum number of back-and-forth turns before stopping
      maxTurns: 50
    }
  })) {
    // Handle assistant messages (Claude's responses and tool calls)
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        // Text blocks contain Claude's written responses
        if ("text" in block) {
          console.log(block.text);
        }
      }
    }
    
    // Handle the final result when the agent loop completes
    if (message.type === "result") {
      console.log("Done:", message.subtype); // "success" or an error type
    }
  }
}

analyzeCode("main.ts");

Cost tracking

Track API costs for billing:

for await (const message of query({ prompt: "..." })) {
  if (message.type === "result" && message.subtype === "success") {
    console.log("Total cost:", message.total_cost_usd);
    console.log("Token usage:", message.usage);
    
    // Per-model breakdown (useful with subagents)
    for (const [model, usage] of Object.entries(message.modelUsage)) {
      console.log(`${model}: $${usage.costUSD.toFixed(4)}`);
    }
  }
}

Production code review agent

Here’s a production-ready agent that ties everything together:

import { query, AgentDefinition } from "@anthropic-ai/claude-agent-sdk";

interface ReviewResult {
  issues: Array<{
    severity: "low" | "medium" | "high" | "critical";
    category: "bug" | "security" | "performance" | "style";
    file: string;
    line?: number;
    description: string;
    suggestion?: string;
  }>;
  summary: string;
  overallScore: number;
}

const reviewSchema = {
  type: "object",
  properties: {
    issues: {
      type: "array",
      items: {
        type: "object",
        properties: {
          severity: { type: "string", enum: ["low", "medium", "high", "critical"] },
          category: { type: "string", enum: ["bug", "security", "performance", "style"] },
          file: { type: "string" },
          line: { type: "number" },
          description: { type: "string" },
          suggestion: { type: "string" }
        },
        required: ["severity", "category", "file", "description"]
      }
    },
    summary: { type: "string" },
    overallScore: { type: "number" }
  },
  required: ["issues", "summary", "overallScore"]
};

async function runCodeReview(directory: string): Promise<ReviewResult | null> {
  console.log(`\n${"=".repeat(50)}`);
  console.log(`🔍 Code Review Agent`);
  console.log(`📁 Directory: ${directory}`);
  console.log(`${"=".repeat(50)}\n`);

  let result: ReviewResult | null = null;

  for await (const message of query({
    prompt: `Perform a thorough code review of ${directory}.

Analyze all source files for:
1. Bugs and potential runtime errors
2. Security vulnerabilities
3. Performance issues
4. Code quality and maintainability

Be specific with file paths and line numbers where possible.`,
    options: {
      model: "opus",
      allowedTools: ["Read", "Glob", "Grep", "Task"],
      permissionMode: "bypassPermissions",
      maxTurns: 250,
      outputFormat: {
        type: "json_schema",
        schema: reviewSchema
      },
      agents: {
        "security-scanner": {
          description: "Deep security analysis for vulnerabilities",
          prompt: `You are a security expert. Scan for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Sensitive data exposure
- Insecure dependencies`,
          tools: ["Read", "Grep", "Glob"],
          model: "sonnet"
        } as AgentDefinition
      }
    }
  })) {
    // Progress updates
    if (message.type === "assistant") {
      for (const block of message.message.content) {
        if ("name" in block) {
          if (block.name === "Task") {
            console.log(`🤖 Delegating to: ${(block.input as any).subagent_type}`);
          } else {
            console.log(`📂 ${block.name}: ${getToolSummary(block)}`);
          }
        }
      }
    }

    // Final result
    if (message.type === "result") {
      if (message.subtype === "success" && message.structured_output) {
        result = message.structured_output as ReviewResult;
        console.log(`\n✅ Review complete! Cost: $${message.total_cost_usd.toFixed(4)}`);
      } else {
        console.log(`\n❌ Review failed: ${message.subtype}`);
      }
    }
  }

  return result;
}

function getToolSummary(block: any): string {
  const input = block.input || {};
  switch (block.name) {
    case "Read": return input.file_path || "file";
    case "Glob": return input.pattern || "pattern";
    case "Grep": return `"${input.pattern}" in ${input.path || "."}`;
    default: return "";
  }
}

function printResults(result: ReviewResult) {
  console.log(`\n${"=".repeat(50)}`);
  console.log(`📊 REVIEW RESULTS`);
  console.log(`${"=".repeat(50)}\n`);
  
  console.log(`Score: ${result.overallScore}/100`);
  console.log(`Issues Found: ${result.issues.length}\n`);
  console.log(`Summary: ${result.summary}\n`);
  
  const byCategory = {
    critical: result.issues.filter(i => i.severity === "critical"),
    high: result.issues.filter(i => i.severity === "high"),
    medium: result.issues.filter(i => i.severity === "medium"),
    low: result.issues.filter(i => i.severity === "low")
  };
  
  for (const [severity, issues] of Object.entries(byCategory)) {
    if (issues.length === 0) continue;
    
    const icon=/__u/nader.substack.com/severity === "critical" ? "🔴" :
                 severity === "high" ? "🟠" :
                 severity === "medium" ? "🟡" : "🟢";
    
    console.log(`\n${icon} ${severity.toUpperCase()} (${issues.length})`);
    console.log("-".repeat(30));
    
    for (const issue of issues) {
      const location = issue.line ? `${issue.file}:${issue.line}` : issue.file;
      console.log(`\n[${issue.category}] ${location}`);
      console.log(`  ${issue.description}`);
      if (issue.suggestion) {
        console.log(`  💡 ${issue.suggestion}`);
      }
    }
  }
}

// Run the review
async function main() {
  const directory = process.argv[2] || ".";
  const result = await runCodeReview(directory);
  
  if (result) {
    printResults(result);
  }
}

main().catch(console.error);

Run it:

npx tsx review-agent.ts ./src

What’s next

The code review agent covers the essentials: query(), allowedTools, structured output, subagents, and permissions.

If you want to go deeper:

More capabilities

• File checkpointing - track and revert file changes

• Skills - package reusable capabilities

Production deployment

• Hosting - deploy in containers and CI/CD

• Secure deployment - sandboxing and credential management

Full reference

• TypeScript SDK reference

• Python SDK reference

This guide covers V1 of the SDK.

V2 is currently in development. I will update this guide with V2 once it’s released and stable.

If you’re interested in building verifiable agents, check out the work we’re doing at EigenCloud here

You can test out the app we’ll be building in this tutorial here. The final codebase is here.

World ID enables you to prove you’re a unique and real human on the internet while keeping your identity private.

For developers, this translates to providing a means of sybil resistance that is becoming both increasingly important, and more challenging, in a world of accelerating AI and automation.

I’ve experimented with many sybil resistance solutions in the past such as GitCoin Passport and the tradeoffs in UX and usability seem very challenging, and there doesn’t yet seem to be a silver bullet, but I feel like World ID’s approach is quite promising.

In the past, WorldCoin brought to mind The Orb, which was controversial to some people and therefore not something that could be used today, at scale, as a single means of identity verification for any app wanting to scale globally in a permissionless fashion.

This is not the case today, as anyone with a mobile device can use the WorldID App to provide unique credentials that would be orders of magnitude harder and more expensive to sybil attack than traditional methods like social authentication or anything on-chain, without the Orb.

Identity methods

There are 3 different authentication methods available through World ID

World ID Device

Allows apps to accept World IDs that haven't yet been verified with an Orb, but are held on trusted devices. This us useful in lower stake scenarios.

This is the method we’ll be using in this tutorial.

World ID Orb

Orbs are devices that verify humanness and uniqueness. The classic Orb signal allows users to prove they are holding an Orb-verified World ID on a trusted device. This is more secure than device only verification.

World ID Orb+

To enable higher security, apps can require face authentication when using World ID, similar to unlocking your phone. This ensures only the issued person can use their ID for that action. Authentication is performed locally on the user’s device thanks to Personal Custody.

Use Cases

User Verification

Use World ID to verify your existing user base if you already have users, or offer a way for users to sign up in another fashion.

User Sign in

Use World ID as an authentication method similar to how you might use Google , Facebook, or GitHub login.

User Actions

Incognito Actions verify arbitrary action a user might take in your app, where each action is independent of other actions. Here are some examples:

• Claiming a one-time discount for a purchase (each discount is independent of other discounts)

• Allowing users to vote in a poll, but only vote per user (each vote is independent, votes from the same person cannot be linked)

• Sharing an invitation to join a platform, limited to five total invites

Similarly to how you might confirm or manage this type of authorization in a database, WorldID

What we’re building

We’ll be building a simple app that allows users to sign in to an app using their mobile device.

We’ll verify the user on the server using the WorldID API, and integrate it client-side using the World ID ID Kit SDK for React.

The user will also be given the option to also connect their wallet to fetch their social profile from Lens or Farcster using Airstack’s API.

We’ll be going the extra mile and adding some nice styling using the ShadCN UI library which is easy to set up with a new Next.js project.

Let’s start building.

Prerequisites

To follow along, you’ll need the following credentials.

1. WalletConnect Project ID

2. Airstack API Key

3. World ID App ID

When creating your World ID App, choose “Production” and “Cloud”:

After you create your World ID App ID, we’ll need to create a World ID incognito action. Set the Action Identifer to auth and set the Maximum Verifications Per Person to Unlimited.

We’ll be using both the App ID as well as the action later when we configure our environment variables.

Project setup

To get started, create a new Next.js app using the Next.js CLI:

npx create-next-app worldid-app

✔ Would you like to use TypeScript? Yes
✔ Would you like to use ESLint? Yes
✔ Would you like to use Tailwind CSS? Yes
✔ Would you like to use `src/` directory? No
✔ Would you like to use App Router? Yes
✔ Would you like to customize the default import alias (@/*)? No

Next, change into the new directory and install the following dependencies using npm, yarn, bun, or your favorite package manager:

npm install @worldcoin/idkit @airstack/node connectkit wagmi viem@2.x @tanstack/react-query next-themes

Next, add the following to tsconfig.json to disable the noImplicitAny TypeScript rule for the purposes of this tutorial:

"compilerOptions": {
  ...   
  "noImplicitAny": false
}

Finally, initialize ShadCN UI:

npx shadcn-ui@latest init

✔ Which style would you like to use? › New York
✔ Which color would you like to use as base color? › Slate
✔ Would you like to use CSS variables for colors? yes

Now, install the following three components using the ShadCN UI CLI:

npx shadcn-ui@latest add button sonner separator

Environment variables

Create a file named .env.local and add the following values:

AIRSTACK_API_KEY="your-airstack-api-key"
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID="your-walletconnect-project-id"

# WorldCoin ID Action Name
NEXT_PUBLIC_WC_ACTION="auth"

# Worldcoin ID App Name
# Remove "_app" from the WorldCoin App ID before setting
NEXT_PUBLIC_WLD_APP_ID="your-worldcoin-app-id"

API Routes

Next, we’ll create our API routes. These will be the back end API endpoints that we’ll be using to interact with the World ID API and the Airstack API.

World ID verification

The first route we’ll create is for verifying a user using the World ID API.

Create a folder in the app directory named verify. In the verify directory create a file named route.ts and add the following code:

//  app/api/verify/route.ts
import { NextResponse, NextRequest } from "next/server"

const endpoint = `https://developer.worldcoin.org/api/v1/verify/app_${process.env.NEXT_PUBLIC_WLD_APP_ID}`

export async function POST(req:NextRequest) {
  const body = await req.json()
  const reqBody = {
    merkle_root: body.merkle_root,
    nullifier_hash: body.nullifier_hash,
    proof: body.proof,
    verification_level: body.verification_level,
    signal: body.signal ?? "",
    action: process.env.NEXT_PUBLIC_WC_ACTION
  }

  const verifyRes = await fetch(endpoint, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
    },
    body: JSON.stringify(reqBody)
  })
  const wldResponse = await verifyRes.json()
  if (verifyRes.status == 200) {
    return NextResponse.json({ code: "success", wldResponse });
  } else {
    return NextResponse.json({ code: "failure", wldResponse });
  }
}

This route verifies the API call coming from the client, which includes the proof, nullifier hash, and merkle root. *see definition of types here.

The action is the action that was configured earlier, which allows this verification to be executed an unlimited number of times.

The signal is a string to be included in the zero-knowledge proof. This is typically used for on-chain actions, and we are optionally passing in a wallet address which could be verified on the server along with a signature for anything you’d like to do on-chain.

User lookup

We have an optional route at /api/get-user that calls the Airstack API with the user’s address to find out if they hold any web3 social accounts, if they do we can address them by their on-chain social profile name.

//  app/api/get-user/route.ts

import { NextRequest, NextResponse } from 'next/server'
import { init, fetchQuery } from "@airstack/node";

init(process.env.AIRSTACK_API_KEY || '')

export async function POST(req: NextRequest) {
  try {
    const { address } = await req.json()
    const query = `
      query GetAllSocials {
        Socials(
          input: {filter: {userAssociatedAddresses: {_eq: "${address}"}}, blockchain: ethereum}
        ) {
          Social {
            blockchain
            dappName
            profileName
            userAssociatedAddresses
            userId
            userCreatedAtBlockTimestamp
          }
        }
      }
    `
    const { data, error } = await fetchQuery(query)
    return NextResponse.json({ data, error})
  } catch (error) {
    console.log('error', error)
    return NextResponse.json({ error})
  }
}

Building the UI

We’re going to build the UI with some nice features like a light/dark mode as well as responsive styling using Tailwind breakpoints. Bear with me as this we will be working across quite a few files.

components/theme-provider.tsx

This lets us set up light / dark themeing

"use client"
 
import * as React from "react"
import { ThemeProvider as NextThemesProvider } from "next-themes"
import { type ThemeProviderProps } from "next-themes/dist/types"
 
export function ThemeProvider({ children, ...props }: ThemeProviderProps) {
  return <NextThemesProvider {...props}>{children}</NextThemesProvider>
}

components/mode-toggle.tsx

Lets us toggle between light and dark mode. This button will live in our nav.

"use client"

import * as React from "react"
import { MoonIcon, SunIcon } from "@radix-ui/react-icons"
import { useTheme } from "next-themes"

import { Button } from "@/components/ui/button"


export function ModeToggle() {
  const { setTheme, theme } = useTheme()
  const nextTheme = theme === "light" ? "dark" : "light"

  return (
    <Button onClick={() => setTheme(nextTheme)} variant="outline" size="icon" className="rounded-full">
      {
        theme === 'light' ? <SunIcon className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" /> : <MoonIcon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
      } 
    </Button>
  )
}

components/connectkit-provider.tsx

This is where we configure Wagmi and ConnectKit

'use client'
import { WagmiProvider, createConfig } from "wagmi";
import { ConnectKitProvider as Provider, getDefaultConfig } from "connectkit";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";

const config = createConfig(
  getDefaultConfig({
    walletConnectProjectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID || "",
    appName: "WorldCoin ID Connect",
  }),
);

const queryClient = new QueryClient();

export const ConnectKitProvider = ({ children }: { children: any }) => {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <Provider>
          {children }
        </Provider>
      </QueryClientProvider>
    </WagmiProvider>
  );
};

app/context.ts

This is the global state that we’ll be using in our app. This includes the user’s wallet address, social profile, and a function to set their profile (all optional as they can opt for only World ID verification).

import { createContext } from 'react'

export const AppContext = createContext({
  address: '',
  profile: null,
  setProfile: () => null,
})

app/context-provider.tsx

This is the component that allows us to update and manage the global state configured in app/context.ts

'use client'
import { AppContext } from './context'
import { useAccount } from "wagmi"
import { useState, useEffect } from 'react'

export function ContextProvider ({ children }) {
  const { address } = useAccount()
  const [profile, setProfile] = useState<any>(null)
  const [verified, setVerified] = useState(false)

  useEffect(() => {
    if (address) fetchProfile()
  }, [address])

  async function fetchProfile() {
    try {
     const response = await fetch('/api/get-user', {
      method: 'POST',
      body: JSON.stringify({ address }),
     }).then((res) => res.json())
     if (response?.data?.Socials?.Social) {
        setProfile(response.data.Socials.Social[response.data.Socials.Social.length - 1])
     } else {
      setProfile({
        profileName: address
      })
     }
    } catch (err) {
      console.log('error fetching profile', err)
    }
  }
  
  return (
    <AppContext.Provider
      value={{
        address,
        profile,
        setProfile,
        setVerified,
        verified
      } as any }
    >
      {children}
    </AppContext.Provider>
  )
}

app/nav.tsx

This is the navigation bar.

'use client'
import Image from 'next/image'
import Link from 'next/link'
import { ModeToggle } from '@/components/mode-toggle'
import { AppContext } from './context'
import { useContext, useState, useEffect } from 'react'
import { Button } from '@/components/ui/button'
import { useDisconnect } from 'wagmi'
import { GitHubLogoIcon } from '@radix-ui/react-icons'
export function Nav() {
  const [isClient, setIsClient] = useState(false)
  const { address, setProfile, setVerified, verified } = useContext<any>(AppContext)
  const { disconnect } = useDisconnect()
  useEffect(() => {
    setIsClient(true)
  }, [])
  if (!isClient) return null
  return (
    <div
      className="flex border-b px-6 py-3"
    >
      <div className='flex flex-1 items-center'>
        <Link href="/__u/nader.substack.com/">
          <div className='flex items-center'>
            <Image
              src="/__u/nader.substack.com/worldcoin.svg"
              width={40}
              className="dark:invert"
              height={40}
              alt="Worldcoin Logo"
            />
              <p className='md:ml-1 text-sm'>
              <span className='font-bold'>World</span> Auth
            </p>
          </div>
        </Link>
        <Link
          href="https://worldcoin.org/world-id"
          target="_blank"
          rel="noopener noreferrer"
        >
          <p
            className='
            hover:text-foreground md:ml-8
            ml-5 text-sm text-muted-foreground
            '
          >
            Learn More
          </p>
        </Link>
        <Link
          href="https://github.com/dabit3/worldid-auth"
          target='_blank'
          rel="noopener noreferrer"
        >
          <GitHubLogoIcon
            className="md:ml-8 ml-5 hover:text-foreground text-muted-foreground"
          />
        </Link>
      </div>
      <div className='flex items-center'>
        {
          (verified || address) && (
            <Button onClick={
              () => {
                disconnect()
                setProfile(null)
                setVerified(false)
              }
            } className='text-xs' variant='link'>
              Disconnect
            </Button>
          )
        }
        <ModeToggle />
      </div>
    </div>
  )
}

For the WorldCoin logo, create worldcoin.svg in the public folder and add this:

<?xml version="1.0" encoding="utf-8"?>
<!-- Generator: Adobe Illustrator 26.4.1, SVG Export Plug-In . SVG Version: 6.00 Build 0)  -->
<svg version="1.1" id="katman_1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" x="0px" y="0px"
	 viewBox="0 0 445.2 315.2" style="enable-background:new 0 0 445.2 315.2;" xml:space="preserve">
<path
class="st0" d="M327.6,115.2c-3-7.5-6.8-14.6-11.3-21.3c-20.3-30-54.7-49.7-93.6-49.7c-62.4,0-112.9,50.6-112.9,112.9
	c0,62.4,50.6,113,112.9,113c39,0,73.3-19.7,93.6-49.7c4.5-6.6,8.2-13.7,11.3-21.2c5.2-13,8.1-27.2,8.1-42
	C335.6,142.4,332.8,128.2,327.6,115.2z M312.5,145.7H183.2c2-7,5.7-13.2,10.7-18.1c7.6-7.6,18.1-12.3,29.7-12.3H303
	C307.9,124.6,311.1,134.8,312.5,145.7z M222.1,66.1c25.7,0,49,10.7,65.6,27.9h-61.3c-17.5,0-33.3,7.1-44.7,18.5
	c-8.9,8.9-15.1,20.3-17.4,33.2h-32.5C137.4,100.8,175.7,66.1,222.1,66.1z M222.1,248.4c-46.4,0-84.7-34.7-90.4-79.6h32.5
	c5.4,29.4,31.2,51.7,62.2,51.7h61.3C271.2,237.7,247.9,248.4,222.1,248.4z M223.6,199.3c-19.2,0-35.4-12.9-40.4-30.5h129.3
	c-1.4,10.9-4.7,21.1-9.5,30.5H223.6z"/>
</svg>

app/layout.tsx

This is the component that configures the nav, global state, and providers we’ve created and passes everything down to be available in our routes. You can think of this as the entrypoint to our app.

import type { Metadata } from 'next'
import { Inter } from 'next/font/google'
import { Nav } from './nav'
import { ConnectKitProvider } from '@/components/connectkit-provider'
import { ThemeProvider } from "@/components/theme-provider"
import { ContextProvider } from './context-provider'
import './globals.css'

const inter = Inter({ subsets: ['latin'] })
export const metadata: Metadata = {
  title: 'World ID Auth',
  description: 'Example of World ID device authentication',
}

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en" suppressHydrationWarning>
      <body className={inter.className} style={{ height: 'calc(100vh - 60px)' }}>
        <ThemeProvider
          attribute="class"
          defaultTheme="dark"
          enableSystem
          disableTransitionOnChange
        >
          <ConnectKitProvider>
            <ContextProvider>
              <Nav />
              {children}
            </ContextProvider>
          </ConnectKitProvider>
        </ThemeProvider>
      </body>
    </html>
  )
}

app/page.tsx

The last component we need to set up is the main view, located at app/page.tsx.

This is a large file, you can also view the code here on GitHub

This component is the only route we’ll be rendering in our app, and contains all of the functionality we’ll need to make this work.

'use client'
import { CubeIcon } from '@radix-ui/react-icons'
import { Button } from '@/components/ui/button'
import { Separator } from '@/components/ui/separator'
import { useModal } from "connectkit"
import { useAccount } from "wagmi";
import { useState, useEffect, useContext, useRef } from 'react'
import { IDKitWidget, VerificationLevel } from '@worldcoin/idkit'
import { Toaster } from "@/components/ui/sonner"
import { toast } from "sonner"
import { AppContext } from './context'
import Link from 'next/link'

export default function Home() {
  const { address } = useAccount()
  const [isLoaded, setIsLoaded] = useState(false)
  const { setOpen } = useModal()
  const { profile, verified, setVerified } = useContext<any>(AppContext)
  const buttonRef = useRef<any>(null)

  useEffect(() => {
    setIsLoaded(true)
  }, [])

  useEffect(() => {
    if (address && !verified) {
      buttonRef.current?.click()
    }
  }, [address])

  async function handleVerify(data: any) {
    data.signal = address
    const response = await fetch('/api/verify', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(data)
    }).then(res => res.json())
    if (response.code === 'success') {
      setVerified(true)
      toast("Successfully authenticated with World ID.")
    } else {
      toast("Authenticated failed with World ID.")
      console.log('error:', response.wldResponse)
    }
  }
  if (!isLoaded) return null

  return (
    <main className="
    p-4 sm:p-12 flex flex-1 h-full">
      <div className="
      rounded-xl border flex-col md:flex-row flex flex-1
      ">
       <div
       className='
       p-6 sm:p-8 rounded-tl-xl rounded-tr-xl md:rounded-tr-none
       md:rounded-tl-xl md:rounded-bl-xl flex flex-1 bg-secondary-100 bg-zinc-900'
       >
        <div className='flex items-start flex-col'>
          <div className='flex justify-center flex-1 '>
            <CubeIcon
             className='w-7 h-7 text-white' />
            <p className='
            text-white
            ml-3 text-lg'>Acme Inc</p>
          </div>
          <div>
           <p className='text-white'>
           Sybil-resistant identity verification powered by <Link rel='no-opener' target="_blank" href="https://docs.worldcoin.org/">World ID</Link>.
           </p>
          </div>
        </div>
       </div>
       {
        verified && (
          <div
          className='
          border-l items-center justify-center
          flex flex-1 flex-col p-6 sm:p-8 '
          >
            <p>
              🎉 &nbsp;Successfully authenticated with World ID.
            </p>
            {
              address && profile && (
                <p className='text-sm mt-3 text-muted-foreground'>
                  welcome, {profile.profileName}
                </p>
              )
            }
          </div>
        )
       }

      {
        !verified && (
          <div
          className='
          md:rounded-bl-none rounded-bl-xl border-l
          items-center justify-center flex flex-1 flex-col p-6 sm:p-8 '
          >
            <div className='flex flex-col items-center'>
              <p className='font-medium text-2xl'>Login or create account</p>
              <p className='text-sm text-muted-foreground mt-2'>
              Connect and verify with World ID.
              </p>
            </div>
            <div className='mt-5 flex flex-col'>
              <IDKitWidget
                app_id={`app_${process.env.NEXT_PUBLIC_WLD_APP_ID}`}
                action=/__u/nader.substack.com/%7Bprocess.env.NEXT_PUBLIC_WC_ACTION || ''}
                onSuccess={(message) => console.log(message)}
                handleVerify={handleVerify}
                signal={address}
                verification_level={VerificationLevel.Device}
              >
                {({ open }) => (
                  <Button
                    ref={buttonRef}
                    className='w-[290px] sm:w-[320px] '
                    onClick={open}
                  >Verify with World ID</Button>
                )}
              </IDKitWidget>
              {
                !address && (
                  <>
                    <div className='relative py-4'>
                      <Separator
                        className='
                          mt-6 absolute inset-0 flex items-center
                        '
                      />
                      <div className='
                       relative flex justify-center text-xs uppercase
                      '>
                        <p className='
                          bg-background px-2 text-muted-foreground
                        '>
                          or
                        </p>
                      </div>
                    </div>
                    <Button
                    onClick={() => setOpen(true)}
                    variant="outline" className='
                    w-[290px] sm:w-[320px] 
                    rounded-lg'>
                      Verify with Wallet & World ID
                    </Button>
                  </>
                )
              }
              <Link
                href="https://apps.apple.com/no/app/world-app-worldcoin-wallet/id1560859847"
                target='_blank'
                rel='noopener noreferrer'
              >
                <p className='
                  text-muted-foreground text-xs mt-4 text-center
                '>
                  Get the WorldID App -&gt;
                </p>
              </Link>
            </div>
          </div>
        )
      }
      </div>
      <Toaster />
    </main>
  )
}

The main thing to call out in the above code is the IDKitWidget component.

This is the component that renders and configures our interaction with our server. The handleVerify function is what you should look at to understand how the API call and the response are handled.

Testing it out

That’s it! You should be able to test it out by running npm run dev.

View a live demo here, and the final codebase here.

React Native AI is a full stack framework for building cross-platform mobile AI apps supporting LLM real-time / streaming text and chat UIs, image services + natural language to image with multiple models, and image processing.

Check out the social announcement here, and the repo here. Please give it a ⭐️ if you think it’s cool!

Video tutorial is also now available here.

I’ve spent the past few months building and launching various AI experiments and products like RoamAround ($10M valuation, 7 million+ users) and AI Buddy ($1,000+ MRR, 2,000 + users).

During that time I’ve learned a lot about how to piece together everything needed to build and launch successful AI apps, lately with a focus on mobile and launching to the App stores.

What I realized was that the base needed to build most of my ideas was the same, but experimenting took a long time because I needed to rebuild these basic components over and over.

React Native AI came out of my need to have a basic, configurable framework to easily spin up new ideas without having to rebuild all of the basic components from scratch.

Some of these components and features:

1. Streaming / real-time responses. Handling and debugging these on both the client and the server can be time-consuming.

2. LLM normalization. The various LLM providers respond in different formats. The idea is to handle these on the server and send back to the client with a consistent interface.

3. OpenAI Assistants. OpenAI Assistants provide a powerful new way to build on LLMs, but the API for doing so is more complex than using a basic LLM. There needs to be a string of API calls and state management for this to work. Having this all set up and ready to use will save me a lot of time in the future.

4. Image processing. Dealing with image uploads and downloads, saving to disk on the server and saving to the device, can be complicated and gets time consuming to debug. Having a plug and play interface and utility functions speeds everything up.

5. Chat UI. Rebuilding components like buttons, text inputs, and chat interfaces is time consuming and tedious. Having a pre-built UI and components for these repeatable UI elements saves a lot of time.

6. Theming / styling. React Native AI comes with 5 prebuilt themes and makes swapping themes out very simple, by adding just a few lines of code. When launching your app, you can ship with just a single theme or give users the option to switch between themes.

Service providers

React Native AI uses the following services:

• OpenAI ChatGPT for 2 types of LLMs as well as OpenAI Assistant, code interpreter, and retrieval

• Fal.ai for an array of image models.

• Anthropic Claude for 2 types of LLMs

• Cohere for 2 types of LLMs including web which gives you access to live, online data

• Bytescale for image processing

Other technology

React Native AI is made possible by great open source tech like React Native, Expo, Node.js, and Express.

Getting started

To get started with React Native AI, run the following command:

npx rn-ai

You’ll be prompted to configure your environment variables either at setup or later. You don’t have to set up all environment variables, you only need to enable the services you’d like to try out.

Countless people are having their lives ripped apart, both Israelis and Palestinians. During this time, I’ve tiptoed around sharing my opinion because I’ve worried how I might be affected. I kiss my kids to sleep, in a safe beautiful home, a privileged life, going about my day without speaking up about the horror that is happening as I type this.

This quote from Martin Luther King Jr. keeps running through my head - "There comes a time when silence is betrayal."

I’m half Palestinian, with a Palestinian wife and kids, having grown up visiting Palestine many times as a kid and through adulthood. My father, who’s family’s home, business, and possessions were ripped away from them during the Nakba, walked through the desert from Lod to Ramallah after their home was taken, and lived there as refugees before migrating to America in the 1970’s.

My family and I have lived in Mississippi most of our lives, a place where racism persists. Over time there have been many incidents, the most extreme was me being beaten unconscious and into the hospital for being a “camel jockey” and “sand n*gger” while walking out of bible class in 11th grade, almost losing vision in one of my eyes. These experiences have driven me to identify more closely with my Palestinian heritage. I have strong opinions about the situation happening there.

I hold my Jewish, Israeli, and Palestinian family and friends dear. They have all always treated me with kindness and hospitality, in the US, Israel, and throughout the Middle East.

It feels impossible to speak about this situation because I know that no matter what I say, there will be people who strongly disagree.

I think that it’s ok to condemn certain actions of the Israeli Government while still loving and empathizing with my Jewish brothers, sisters, and friends – supporting their right to live a safe, happy life, in their own country, Israel.

As for Hamas, their barbaric acts of terrorism, their attacks and murders of innocent people in the past and on October 7 are horrific and I condemn them. They have caused immeasurable suffering for the Palestinian people, and have weakened the Palestinian cause. They should immediately release all hostages in an attempt to negotiate a ceasefire.

Some might argue that the conflict happening there for generations is complicated, but what happened to spark the current wave of violence was not - it was horrendous and brutal, and without justification. It is never ok to target children or civilians.

I also condemn the atrocities being perpetrated by the Israeli government in Gaza. The collective punishment of a besieged and helpless people is evil, cruel, and is in flagrant violation of international humanitarian law. It is, by definition, a war crime [1] [2] .

There are people in this world who argue that Hamas murdering and terrorizing innocent people is wrong, while cheering on the people in a proper militant uniform of their choice doing the same thing. In reality, both are horrific and unjust.

If Israel has a right to defend itself against brutal attacks on civilians and breaches in international law (it does), then does Palestine get afforded the same rights? The answer from the US, Israeli, and many western nations has been a resounding NO. These laws do not apply to Israeli government or militant operations.

For instance, here is a non-comprehensive list of incidents since 2009, where many women, children, health workers, and members of the press were murdered:

• 2014 when four Palestinian boys, aged between 9 and 11, were murdered by an Israeli airstrike while playing on the beach.

• 2014, multiple acts of violence involving United Nations Relief and Works Agency schools. In one case in Jabalia, at least 15 people were killed and approximately 100 injured when the school was mortared.

• Between 2018-2019, over 200 killed in the “Great March of Return" protests

• 2009 bombing of Al-Quds Hospital, resulting in the death of at least 42 people, with over 50 others injured.

• 2009, when 29 members of the Samouni family were killed when their house was mortared and many other family members injured.

• 2014 bombing of a Market in Shuja'iyya where at least 17 people died, and approximately 200 were injured.

• 2012 airstrike on the home of the the Al-Dalou family, killing 12 people and several others injured.

• 2014 destruction of the Gaza Power Plant, the subsequent lack of electricity severely affected medical services, water supply, and sanitation, indirectly affecting thousands.

• 2014 when nine people were killed, and at least 15 injured when a civilian Cafe was bombed in Khan Yunis.

• 2009 when Israel bombed the Al-Fakhura School, resulting in over 40 deaths and more than 50 injuries.

• The systematic forced evictions and stealing of land and homes from Palestinians to give to Israelis and Israeli settlers. Too many incidents to list.

No media interviews with their families, no tears from anchors, no Palestinian flags projected onto government buildings, no statements of solidarity from companies, and no “Palestine has a right to defend itself”.

Beyond the killings, the humanitarian crisis which existed before this war started has become much worse, with water, food, electricity, internet, medicine, and communications cut off or prohibitively restricted, civilian homes, businesses, and infrastructure destroyed. The looming ground invasion and displacement of over 1 million Palestinians from their homes will only compound the situation.

If this were happening to any other population in the world it would be rightly condemned, immediately and unequivocally.

All innocent life is equal

How valuable is a human life? It has been incredibly hurtful for me to witness the stark contrasts in the answer to this question across different groups of people around the world.

Here in the United States, it has not been surprising to see a population who collectively shrugged off the murder of hundreds of thousands of innocent Iraqi children and civilians in a war based on the false pretenses of their government, to only show empathy toward non-Arab civilian deaths in this conflict – these past weeks but also over the past few decades.

The lack of empathy in much of the Western world is something many people find deeply troubling. In the United States we have collectively mourned only one side of this tragedy. It is important to recognize, honor, and mourn the Israeli lives lost and the people suffering there. But why are we not doing the same for innocent Palestinians? Over the past 2 weeks alone, it is estimated that over 1,700 Palestinian children have been killed. This does not mean we should not mourn the Israeli lives lost, it just seems inhumane to choose to mourn based solely on ethnicity, race, or religion – especially when 50% of those being killed are kids.

The fact that I’ve realized is this – there are people who support the terrorism, murder, and collective punishment of innocent people, as long as it’s performed against the proper ethnicity. To them, Palestinian lives are considered to be sub-human.

This goes both ways. If you are angry about what has been happening to the people of Gaza over the past few weeks but not also enraged about the innocent Israelis who were killed, you are no better.

Human rights

Both Israelis and Palestinians deserve peace and human rights. Israel is a small country, with a small number of people compared to the surrounding Arab nations. Many of these surrounding countries are full of people with animosity towards the Israeli government. While this animosity is mainly directed towards the actions of their government over the years and not the individuals themselves, I can’t imagine how it might feel to live in Israel as a Jew knowing that many of your neighbors dislike you, and openly argue that your country should not even exist.

What I have personally witnessed and experienced are Arabs and Israelis living together in peace in Tel Aviv, Jerusalem, Haifa, and many other places there. To argue that peace between these people is not possible is to dismiss this reality.

So if this is possible, why do terrorists exist in places like Gaza? Does terrorism exist in a vacuum? There is never justification for terrorism. Is it wrong though to analyze and find the answer to this question? Terrorism is bad, so diagnosing ways to eliminate it seems like a righteous thing to do.

This conversation is one the most controversial in all of this. Those wanting to spark more fear, hatred, and division will use it to do so, but for the intellectually honest it is straightforward to understand.

Radicalism fueled by a combination of anger and hopelessness breeds terrorism. Where does this hopelessness and anger come from?

Displacement, forced evictions, and settlements

Palestinians are systematically forcefully evicted and displaced from homes and land that they own. These displacements usually occur without adequate notice or compensation, leaving families homeless.

While people are being forced out of their homes and land, they watch as more and more settlements are built on the land that was once theirs. The United Nations has consistently stated that Israeli settlements are illegal under international law and are an obstacle to peace.

Settlement expansion still continues relentlessly. Estimates say that there are now over 140 official settlements and about 120 "outposts" (smaller, usually unauthorized settlements). By the end of 2022, the populations living in these settlements was estimated to be over 475,000.

In 2022, Israel approved plans for 4,427 new settler housing units, the highest number since Peace Now started tracking in 2012.

Detention without trial

Many Palestinians, including minors, have been detained over the years, often without charges or trials. Some detainees have faced torture.

Collective punishment

The Israeli government enacts blockades, closures, the demolitions of homes, and the destruction of civilian infrastructure as collective punishment for the actions of a few individuals.

The Gaza blockade in particular has had a devastating impact on the civilians living there, restricting access to basic necessities like food, water, and medical supplies. There are people who have never been allowed to leave Gaza during their lifetimes, a strip of land 25 miles long with a maximum width of 7.5 miles.

Collective punishment is not just cruel, it is also prohibited under international law.

Restriction and control of movement

Palestinians face severe restrictions on their movement. These restrictions hinder access to essential services, education, and employment opportunities.

People living in the West Bank do not face a full blockade, but still have to receive approval and permits to move throughout the region, facing numerous roadblocks, checkpoints, barriers, and inspections run by the Israeli military along the way.

Excessive use of force

When people decide to collectively speak up or perform activism against any of these injustices, Israeli security forces often use excessive and disproportionate force against Palestinian protesters and civilians, including the use of live ammunition.

Human rights depend on the human

The message to the Palestinian population has been loud and clear: human rights are applied selectively based on borders, races, ethnicities, and religions

Israel’s right to exist

The Jewish people have maintained a presence there for thousands of years, long before the creation of the state of Israel. Israel is the only Jewish homeland that exists. Millions of Jewish refugees fleeing persecution settled in Israel, providing a vital sanctuary. They have faced centuries of persecution around the world. Beyond WW2, many Israelis are themselves refugees or the descendants of refugees from many parts of the Arab world.

Most Israelis that I know acknowledge the right for Palestinians to also have their own country, and want to live peacefully alongside them. They respect, are friends with, and do business with each other.

I support a two state solution. To get there, compromises need to be made by both Israelis and Palestinians, and the extremists from both sides need to be ousted completely.

To say this is a gross oversimplification of course, and does not take into account the complexities of local governments and politics on both sides, religion, US involvement, Zionism, or the financial support of Hamas by Iran and Saudi Arabia over the years among many other things. I encourage everyone to do their own research, dive into the history, and try to understand both sides. I still have hope that there can be peace.

Fighting for what is yours

One of my strongly held opinions is that people have the right to stand up for themselves and fight for what’s theirs. I believe this whether you are American, Mexican, Israeli, Moroccan, Bengali, or yes – even Palestinian.

This is not an unpopular opinion. Indeed, protections for property owners, including provisions allowing lethal force in some cases, have even been codified in the laws of at least 28 states and Puerto Rico.

These are some of the most popular and celebrated laws from Conservatives in America today. So why do we see a reversal from certain people about this issue when being applied to other nationalities, nations, and ethnicities?

I cannot say what I would do in the situation of someone in Palestine who’s had their home taken from them, but terrorism or violence against innocent people is never acceptable or justified.

What I can share is what I would do in my own personal situation and life, as a civilian living in the United States. If someone stole, then lived on my family’s land, while attempting to imprison me and my family for the rest of our lives, I would fight back against the people attempting to take it from me, by any means necessary. Again, this is a very popular sentiment in the US – something enshrined into US law.

Extremism

Though many of the images and videos I’ve seen online are grim, I’m thankful for social media in times like this. We get a real and uncut view of what is happening. We see and hear perspectives we would have never had in the past from mainstream media. Social media has shined a light on many injustices over the years that we would have never known about without it.

Social media is also full of people trying to convince you that their side is right. The truth is, it’s nearly impossible to change someone’s mind during these interactions, but getting an uncensored view of everything happening on all sides does help paint a more clear picture.

Many of these people are sharing cherry-picked or extreme examples of one side or the other doing or saying something to make their case, but these extremes do not represent the whole and are meant to stir more division. We’ve already seen violence against both Jews and Arabs outside of the region probably due to the rise in propaganda from both sides.

Nuance is where the truth lies, but it is the enemy of the extremist. Regardless of the actual truth, extremists will take any situation, statement, message, or incident, and try to spin it to into something that can be simplified in order to suit their own agenda and narrative. Including this writing.

The end

I have been afraid to share my views because I know how controversial of a topic this is. I know I might lose friends, followers, and job opportunities because of my views. But if I can shed more light on the situation, and bring even another ounce of humanity into it, it will have been worth it.

I encourage you to look into and research the history of this conflict yourself, especially listening to people with opposing opinions and lived experiences, to come to your own conclusion.

In this tutorial you’ll learn how to fine-tune GPT with your own custom data from scratch.

To view the final codebase for this tutorial, click here. The video for this tutorial is available here.

API

The OpenAI GPT APIs and SDKs make it easy to fine-tune a model using either Python, Node.js, or just an HTTP request. There are also quite a few community-maintained libraries for other languages like PHP and Ruby.

In this tutorial we’ll be using the OpenAI Node.js SDK. This SDK is simple to use and allows you to make API calls to OpenAI in just a couple of lines of code.

For instance, to retrieve a completion we can just call the createCompletion method:

const response = await openai.createCompletion({
  model: 'davinci',
  prompt: "What is Lens Protocol",
  max_tokens: 200
})

In our case, we’ll just be replacing the davinci model with our own model that will use our custom data set we’ve uploaded for training.

Prerequisites

To follow along with this tutorial, you’ll need to have the following installed on your machine:

• Python

• Node.js

You’ll also need an OpenAI API Key. You can get one at https://openai.com.

Getting started

To get started, we’ll create a new Node.js project in an empty directory:

mkdir custom-ai-model
cd custom-ai-model
npm init --y

Update the new package.json file to use ES Modules by adding this line of configuration:

"type": "module",

Next, set the environment variable to hold your OpenAI API Key. You can set this in your terminal session or in a configuration file like .bashrc or .zshrc:

export OPENAI_KEY="your-api-key"

Next, we’ll install the openai npm package:

npm install openai

Finally we’ll install the OpenAI CLI and the OpenAI datalib:

pip install --upgrade openai openai"[datalib]"

Now we’re ready to start writing some code!

Creating the training data

There are a handful of models available from OpenAI, but when fine-tuning the original GPT-3 base models are currently the only models available to start from, like davinci, curie, babbage, and ada. We’ll be using davinci.

Your data needs to be created in a JSONL document in the following format, with each declaration separated in a new line:

{"prompt": "<prompt text>", "completion": "<ideal generated text>"}
{"prompt": "<prompt text>", "completion": "<ideal generated text>"}
{"prompt": "<prompt text>", "completion": "<ideal generated text>"}

It is recommended to provide at least a few hundred of these examples, most sources recommending 500 or more.

In my experience, creating a few dozen inputs will at least give you some basic result that you can test out in this tutorial, but it is not enough to use as a production ready product.

From the docs: … performance tends to linearly increase with every doubling of the number of examples. Increasing the number of examples is usually the best and most reliable way of improving performance.

Once you’ve created your document, OpenAI provides a command line utility which will improve the format of your data and is recommended to run before you upload.

openai tools fine_tunes.prepare_data -f <LOCAL_FILE>

You can view, and even copy and use, my example data set here for this tutorial.

Once your data set is ready, we can create a script to upload it to OpenAI.

Creating the API interface

This file will define the API that we’ll be using to interact with the OpenAI APIs.

Since we’ll be re-using this code over and over, we’ll separate it into it’s own file and just import it into our other files.

Create a file named api.js and add the following code:

/* api.js */
import { Configuration, OpenAIApi } from 'openai'
const openaiApiKey = process.env.OPENAI_KEY
const configuration = new Configuration({
  apiKey: openaiApiKey
})

export const openai = new OpenAIApi(configuration)

Uploading the training data

Now that we’ve created the API, we can use it to upload our file to use later.

Create a file named uploadFile.js and add the following code:

/* uploadFile.js */
import { openai } from './api.js'
import fs from 'fs'

async function upload() {
  try {
    const response = await openai.createFile(
      fs.createReadStream('./data_prepared.jsonl'),
      "fine-tune"
    );
    console.log('File ID: ', response.data.id)
  } catch (err) {
    console.log('err: ', err)
  }
}

upload()

Next, run the script:

node uploadFile.js

When the upload is complete, take note of the the File ID that is logged out, we’ll be needing it in the next step.

Creating the Fine Tune

Now that we’ve uploaded the training data and have the file ID, we can use it to custom train our model.

To do so, create a new file named createFineTune.js and add the following code:

/* createFineTune.js */
import { openai } from './api.js'

async function createFineTune() {
  try {
    const response = await openai.createFineTune({
      training_file: 'your-file-id',
      model: 'davinci'
    })
    console.log('response: ', response)
  } catch (err) {
    console.log('error: ', err.response.data.error)
  }
}

createFineTune()

Next, execute the script to start fine tuning your model:

node createFineTune.js

Listing your Fine Tunes

Once the fine tune is created, it will take some time to process. We can get the status of the fine tune, as well as the model ID, by calling the listFineTunes API method.

Create a new file named listFineTunes.js and add the following code:

/* listFineTunes.js */
import { openai } from './api.js'

async function listFineTunes() {
  try {
    const response = await openai.listFineTunes()
    console.log('data: ', response.data.data)
  } catch (err) {
    console.log('error:', err)
  }
}

listFineTunes()

Run the script.

node listFineTunes.js

It will take the process a few minutes to finish. Once the process is completed and you run the script again, you should see the fine_tuned_model field populated with the new model ID.

Take note of this fine_tuned_model ID, you’ll need it in the next step.

Testing it out

Now that the fine tune has processed and our. new model is ready, we can try it out!

Create a new file named createCompletion.js. Here, add the following code. Be sure to update the fine_tuned_model value with your model name:

/* createCompletion.js */
import { openai } from './api.js'

async function createCompletion() {
  try {
    const response = await openai.createCompletion({
      model: 'your-custom-model-name',
      prompt: 'What is Lens Protocol',
      max_tokens: 200
    })
    if (response.data) {
      console.log('choices: ', response.data.choices)
    }
  } catch (err) {
    console.log('err: ', err)
  }
}

createCompletion()

Run the script:

node createCompletion.js

🎉 Congratulations

You’ve successfully deployed your own custom model using GPT3!

To view the final codebase for this tutorial, click here.

Due to the flywheel of network effects, strong developer communities are one of the most sought after components when building out a developer-facing software company or product. In fact, network effects are one of the most important things that come to mind when understanding the value of developer communities:

Network effect - “A phenomenon whereby a product or service gains additional value as more people use it.”

In software, and particularly in open source, the value of an ecosystem continues to grow stronger and stronger as more developers build within it.

A good analogy would be a popular ingredient like Sriracha hot sauce entering the market that becomes so popular that everyone starts creating recipes based on that brand itself, using it as a core building block. A new, better hot sauce could enter the market, but everyone knows and trusts the older brand, and there are 1000’s of recipes who call it out specifically, with dishes even named after it. It is hard to compete once a brand has achieved market saturation.

We often see superior software products enter the market, while remaining unable to gain market share in their category due to the fact that they have no interoperability with everything else that has been integrated with an older, and what could be considered inferior, product – but one with a larger and more mature developer ecosystem

One of my favorite things to point out is that the more people building in an ecosystem, the more people build in that ecosystem. So how do you bootstrap a strong and resilient ecosystem, and do it as quickly as possible?

This is what this post is about.

To understand my perspective

I think it’s worth understanding my own story and background of how I got into the industry. Or, we can just jump to the main points.

One of the most popular tweets I have ever made was outlining my own personal journey as a developer:

This tweet resonated with a lot of people because it showed how late I started programming, the fact that I did not have a formal education, and that I was not ashamed of either of those things.

The main takeaway I like to point out from my experience getting my foot in the door is that I am self taught, but that I owe all of what I know to people who came before me that I label bridge builders.

A talk that had probably the most impact on me in my life was a keynote titled Building Bridges by Aaron Frost at NG Vegas 2015.

In this talk Aaron cemented powerful values that had already been living in my head for sometime — that many of us are here, living happy and succesful lives, due only to the fact that there have been countless people that have helped us out along the way.

This poem in particular touched me a lot:

The Bridge Builder

BY WILL ALLEN DROMGOOLE

An old man going a lone highway,
Came, at the evening cold and gray,
To a chasm vast and deep and wide.
Through which was flowing a sullen tide
The old man crossed in the twilight dim,
The sullen stream had no fear for him;
But he turned when safe on the other side
And built a bridge to span the tide.

“Old man,” said a fellow pilgrim near,
“You are wasting your strength with building here;
Your journey will end with the ending day,
You never again will pass this way;
You’ve crossed the chasm, deep and wide,
Why build this bridge at evening tide?”

The builder lifted his old gray head;
“Good friend, in the path I have come,” he said,
“There followed after me to-day
A youth whose feet must pass this way.
This chasm that has been as naught to me
To that fair-haired youth may a pitfall be;
He, too, must cross in the twilight dim;
Good friend, I am building this bridge for him!”

For most my life I had rarely been able to give anything back as I myself was still figuring things out for myself. But as I found myself gaining some tiny traction in the software industry, I became deeply compelled to start doing everything I could to give back in any way I could.

As a self-taught developer, I also felt so much gratitude to those who came before me that I became enthusiastic and almost obsessed with passing on anything and everything that I picked up that helped me along the way in the hope that it would also help those who came after me.

Building bridges as a developer

I realized that as a developer, there are many ways you can be a bridge builder:

• Teaching / speaking at meetups and conferences

• Answering questions on stack overflow

• Mentoring new developers

• Open sourcing your work

• Blogging / videos about what you’ve learned

• Building communities focused on public goods

• Sharing ideas and opportunities on social media

The goal being to genuinely help those who come after you to achieve what you have achieved and more.

Some of the ways that I built bridges in my career:

• Created first MS coding meetup meetup 2014

• Created first MS coding school in 2014 (failed)

• #1 on Stack Overflow for React Native

• Built and open sourced React Native Elements

• 15,000,000 views on technical blog

• Founded Developer DAO

Bridges to networks

Something I did not realize was happening early on during this time was how valuable the networks I began organically building were becoming.

As you make this part of your day to day, you often lose track of how many people you’ve helped in some way. Often people will find your blog posts or video,s use it to kick start a company or land a job. Every time you help someone become succesful, they remember and hold on to that experience.

Over time you build out an enormous network. If you’ve done things right, people also begin to gain trust in you — or at least trust that you’re being honest and straightforward even when you are wrong.

During my career, moving from engineering, to running my own company, to participating in DevRel at scale, what I came to realize was this:

The most important component of building high impact developer communities is Building Bridges.

Framework for Developer Impact

FOR THE INDIVIDUAL

Before we get into building communities, let’s first start with the individual. To make this simple, I created a visual hierarchy that to me can be a framework to aspire to as an individual working to build a great developer community.

While I believe starting from the bottom and going up is a good approach, there are always hacks that enable higher impact while skipping some of the in-between.

Framework for Developer Impact

FOR THE COMPANY // TEAM // PRODUCT

While I have had experience in the past year taking part in building a shared community with Developer DAO, most of my experience comes from building communities around software ecosystems and products, so that is really the main focus of this post and the following framework.

1. Build something useful

This should be obvious (but obviously isn’t), but you first need to have something that people want.

Instead of trying to build a community around something mediocre or worse, you should go back to the drawing board and experiment more.

2. Have amazing docs

Once you have a quality product, your documentation will be the main entrypoint to your developer ecosystem. If you’re lucky enough to get developers to notice you, you absolutely have to give them the best shot possible at being successful by having pristine docs.

It’s unreal how many times I’ve seen multi-million dollar companies spend countless hours (and large amounts of money) to build an incredible piece of software, while having documentation that loses 99% of the developers who try and use it for the first time.

Your developer docs should have a no-brainer quick-start guide that makes no assumptions and gets developers from zero to one, preferably all in a single page without needing to navigate anywhere.

Giving new developers this mental win and quality first impression is unbelievably important, and should be top of mind when building out your documentation.

3. Provide a place for conversations to happen.

Most teams know this at this point, but there should be a dedicated channel or platform for everyone in the community to gather, ask questions, and form relationships.

You can go beyond this and create curated community chats with the top builders within your community. A good way of going about this is creating a private Telegram group where high profile people and engineers from your team are invited along with the most active and high quality builders in your community. This gives builders the opportunity to have direct contact to answer important technical questions, but also gives them a feeling of importance as you are placing them in a special group. It is a win-win and not a heavy lift.

4. Optimize for many-to-many relationships

Once you have the foundation in place to bring developers success, it’s time to focus on building many-to-many relationships with your community.

There is only so much an individual can do to have an impact. Building a strong developer community means being active on social media, providing high quality documentation, creating tutorials and videos, collaborating with creators and builders in the ecosystem, speaking and teaching at conferences and events, … the list goes on.

Instead of trying to do all of this yourself, or with with your team (regardless of the size), find ways to incentivize community members to take on some of this responsibility.

The way this is done is by identifying and incentivizing high quality the superstars within your community.

5. Identify and incentivize your superstars.

Superstars in your community can be OSS developers, blog authors, YouTubers, speakers, teachers, succesful teams building software with your product, or trusted developers with their own large networks.

Ambassador programs have become a popular way to do this, providing builders with exclusive privileges, special Discord roles, swag, and VIP access to private events.

Beyond this, you can do things like have profile people within your team share their work and wins publicly, create private one-on-one communication channels with engineering or leadership support, or just straight up pay or hire them on a contract basis.

How to effectively identify these standout community members? You can of course do this manually, but Orbit does a pretty good job of automating this. I’ve used this in the past with some success and would recommend trying it out to identify who your most active community members and contributors are. You can also learn more about the Orbit Model of community here.

6. Optimize for scalable digital content

This idea is simple yet teams rarely truly understand how powerful it is.

If you think about the ROI for attending an event vs creating something digital that is of high value / quality, almost all events are blown completely out of the water. As you’ll see in the next section this doesn’t mean you should not prioritize some budget for IRL events, it just means you need to think about them in a different light.

Let me give you an example:

At events like ETHCC, Token2049, and ETH Denver, I witnessed over and over people who flew across the world (literally), spent thousands of dollars, and checked out of their day-to-day work only to sit on a panel or present on a stage with a crowd of 5 - 30 people.

In contrast, I’ve seen high quality educational content reach 10,000 to 100,000 people on average.

A video clip usually costs ~50x less to produce and receives ~100x as many viewers as an in person talk. This means mathematically, even if we’re scaling these numbers down, in-person events are around 500x less scalable and efficient.

Imagine sending 5-10 people to speak at most of these events, blowing through hundreds of thousands (often millions) per year, only to hit around 1% of the reach as someone sitting in front of their computer writing a tweet or recording a video.

Take this seriously. Weave it into your DNA. Make it part of your strategy. Every time a dollar is spent, ask yourself this: could this dollar be spent elsewhere to have a higher impact? When talking about events, the answer is usually yes.

7. Use IRL events to build relationships, not educate

I wrote more in depth about my event strategy here.

I still think in-person events are important, but for different reasons than I did in the past.

Outside of hackathons, use IRL events to meet and form stronger relationships with developers, founders, community members, etc… That’s literally it.

The one nuance I’d call out regarding educational events is that in-person hackathons offer an opportunity to educate as well as form relationships, and I think are valuable.

I think some realistic numbers to keep in mind might be 2 in-person hackathons per year, and an in-person event per year in each main region you are interested in (e.g. USA, Europe, APAC, Asia, etc..).

This might equal 4-7 in-person events per year for your main or DevRel team, and for everything else, it can be scaled down dramatically by sending a small handful (1-3) of high impact team members to other important events.

By taking this approach, you’ll free up resources to focus on more scalable content and educational resources.

8. Prioritize diversity

The world is a large and diverse place. We often grow up in and around environments that are bubbles of what is actually out there in the real world.

Regardless of how much we read, experience, or go out of our way to understand other people’s lived experience, we will never be able to have the perspectives of people who have lived different lived experiences.

More diversity of lived experiences results in more diverse ideas and synergies, as well as an understanding of the wants and needs of people on the other side of the screen of the products that we are building.

We should go out of our way to optimize for diversity in all aspects of our community, from gender, to sexual orientation, to geographic region, to income level, to … well everything!

From a straight up business / logical perspective, this will also create a more welcoming space, enabling a larger pool of developers to feel comfortable joining and being a part of your community.

9. Help people where they are

EVEN IF THEY ARE NOT BUILDING WITH YOUR PRODUCT.

A huge mistake many community builders make is that they make it all about themselves or about their own products.

If you want developers to listen to you, you have to build trust. It’s hard to build trust if you are constantly only shilling your own product at every opportunity.

It’s simple really. Find opportunities to be there to help developers, and actually try to help them regardless of what the solution is.

This means that if someone has a question that has nothing to do with what you do or what you are working on, do your best to help them, and point them to the proper solutions even if it means pointing them to a competitor, and if it means you never get to talk about what you are doing

10. Be transparent about tradeoffs

Another part of building trust is being just as transparent and straightforward as you can be about the negatives of your product as you are the positives.

When someone asks you about, or you have the opportunity to talk about, what you are working on, being transparent about both sides builds trust in that you are indeed telling the truth.

While these last two points might seem obvious to you, you’d be surprised at how many teams do not act in this way.

11. Contract out your weaknesses

At the time of this writing, DevRel (Developer Advocacy and Developer Relations) is among the most in demand roles that I know of in the software industry and the demand continues to grow.

A good DevRel is good at programming, communication, writing, speaking, content creation, social media, and many other things.

When hiring for Developer Relations roles its often hard to find someone who is able to do all of these things and do them well. Even if you do find the right person, most people usually have a handful of things they are naturally better at, and hiring for a handful of these specific qualities often enables you to find people who are exceptional at certain tasks.

Instead of looking for those few unicorns, consider instead hiring one high quality individual who can manage the DevRel responsibilities, then outsource the rest.

There are actually numerous benefits to this approach:

1. It’s less expensive. Instead of hiring someone full time, you can contract out individual tasks like creating a tutorial, video series, or OSS library.

2. There’s less risk. Instead of hiring someone full time and buying in with all of the things that go along with a full time employee, like benefits and such, you are on a month-to-month contract that has no obligations to continue at all if they are not performing well.

3. More specialization. You can hire for the exact things you need.

4. Better talent. Because contracting is less expensive, you can theoretically pay more to get the highest talent available. If you are paying someone $200K / year salary + benefits + etc.., this comes out to around $16,000.00 per month. This type of money opens the door to some of the highest quality talent around. If your budget is higher, you will be able to hire almost anyone, but to be honest you can bring in high quality specialists for around half of that per month on a contract basis.

5. If you break the above budget down and instead decide to use it to incentivize community members, it also goes quite a long way. Imagine if you decided to pay your top 15 community contributors $1,000 per month for work they were already essentially doing?

END