Use cases

nod runs the same agent in four places: the interactive shell, one-shot nod ask runs, editors over ACP, and your own application through the SDK. Pick the one that fits the job.

Understand an unfamiliar codebase

Start nod in the project root and ask about real paths:

cd path/to/project
nod

Explain how a request flows from src/server.ts to the database.
List the files involved and anything that looks fragile.

Type @ to reference a specific file. Add project instructions so every session starts with your conventions. If the work spans more than one repository, add the others with nod workspace add PATH; see Additional workspaces.

Fix a bug or build a feature

Describe the outcome and how to verify it:

The /login route returns 500 when the email is missing. Find the cause,
fix it, add a regression test, and run the test suite.

nod reads code, edits files, and runs commands under your permission mode. Press enter with a follow-up to steer it mid-turn, escape to stop, and ctrl+o to review what changed. Pick up later with nod resume last.

Draft pull requests and issues

Let nod summarize the current branch into a pull request:

nod pr "focus on the migration risk"

The draft is printed for review. Add --create to publish it with gh. nod issue works the same way for bug reports:

nod issue --create "flaky timeout in the upload test"

Automate with scripts and CI

nod ask runs one request and exits. Markdown goes to stdout and progress to stderr, so it composes with other tools:

git diff main | nod ask "review this diff for bugs; reply with a short list"

Use --json when a program needs structured output, and --no-save for throwaway runs:

nod ask --json --no-save "summarize the current changes" | jq -r .final_output

Chain steps in one session with --resume last:

nod ask "add input validation to src/api/users.ts"
nod ask --resume last "now add tests and run them"

Noninteractive runs never wait for approval; actions that need a human fail instead. Configure permission rules for what the job may do, and sign in on the runner before the job starts. See nod ask for every flag.

Work from screenshots

Attach a design or an error screenshot:

nod ask --image ./mockup.png "build this settings page in src/ui/Settings.tsx"

In the shell, use /image ./path.png. See Vision.

Connect your tools

Give nod access to issue trackers, databases, or internal APIs through MCP servers:

nod mcp add --transport http linear https://mcp.linear.app/mcp
nod mcp auth linear

See MCP. Package repeatable workflows as skills and invoke them with $. For research beyond the repository, nod can use web search; for large tasks it can delegate to subagents.

Use nod from your editor

Editors that speak the Agent Client Protocol can launch nod as their agent:

{
  "command": "/absolute/path/to/nod",
  "args": ["acp"]
}

The editor's working directory becomes the workspace. See ACP server.

Build nod into your application

The SDK runs the same agent in-process:

import { createAgent } from "@anturno/nod/sdk";

const agent = await createAgent({ auth: { provider: "codex" } });
try {
  const turn = agent.prompt("Summarize README.md in three bullets.");
  for await (const event of turn) {
    if (event.type === "text_delta") process.stdout.write(event.delta);
  }
  await turn.result;
} finally {
  await agent.close();
}

Start from the examples: a readline chat, an HTTP route, and an embedded terminal. See the SDK API reference.

Browse all nod documentation

View this page as Markdown · llms.txt