niri #

niri is an llm harness for coding sessions and persistent agents. run it in a project directory to start coding, or use the server to manage agents with their own identity, memory, tools, and discord connections.

getting started #

requires node.js 22.12+ and npm 10+.

npm ci
npm run build:packages
npm link
niri

npm link installs the checkout's niri command. without it, use npm run niri --.

niri login openai-codex          # sign in with oauth
niri models                      # list provider/model choices
niri sessions                    # sessions for the current directory
niri --resume <session-id>
niri --help

in chat, /t toggles reasoning, /v expands tool output, and /status shows usage. escape stops the active turn without closing the session. coding turns finish after a plain reply.

persistent agents #

one server can manage several agents, each with a separate durable home.

niri serve                       # start the control server daemon
niri agents create mira          # create a stopped agent; prompts for setup
niri agents start mira
niri chat mira

use niri agents list, stop, or restart to manage agents, and niri serve status, logs, or stop to manage the server. npm start runs the server in the foreground instead.

configuration #

agents/mira.example.yaml shows model, discord, delegation, mcp, webhook, and runtime settings. for file-based setup, copy it to agents/mira.yaml, fill in the values, and run chmod 600 agents/mira.yaml before starting the server.

files in agents/ are initial seeds, not the live source of truth. after import, use niri config --help or the config api to manage durable configuration; editing a seed file does not overwrite live changes on restart.

tools and isolation #

client: local runs an embedded tool host. a separate machine can run one with:

npm run start:tool-host

connect through an http tool-host url or use client: iroh for an authenticated, encrypted dial-out connection. keep http tool-host endpoints on loopback or a trusted private network.

workspace sets the initial working directory; it is not a sandbox. provide a separate container, vm, or machine when agents need isolation.

memory and storage #

coding sessions live under ~/.niri (NIRI_HOME overrides it):

• sessions/ — saved conversations, grouped by project directory.
• projects/<directory-key>/memory.md — shared project memory.
• auth.json — private oauth credentials.

persistent agents keep their own home, containing soul.md, memories/, state/, and niri.db. memory belongs to the agent runtime, not its tool host. long conversations fold into recursive summaries while original messages remain retrievable from the archive.

treat identity and memory files as private. for a full backup, stop the agent and preserve its entire home, not just the markdown files.

development #

npm run typecheck
npm test
npm run build