DEVELOPER INTELLIGENCE / BUILT INTO NIRAL

Niral DI.

Your project. Your model.
Your call.

Developer Intelligence in your terminal. Understand a codebase, make reviewed changes, and start a Niral app with your chosen provider. Every workspace tool waits for your approval.

Set up DI Explore the commands
0 runtime dependencies3 provider protocols5 CLI commands Per-tool approval

01 / THE WORKFLOW

Intelligence proposes.
You decide.

A bounded tool loop connects your selected model to a small set of workspace operations. Approval is required for reads, not just writes.

  1. 01

    You set the task

    An explicit prompt, workspace root, provider and model.

  2. 02

    The model proposes

    A structured tool call with validated arguments.

  3. 03

    You approve

    Review each call. Only y approves; Enter denies.

  4. 04

    DI applies

    Check paths and hashes, back up originals, then write.

Tool results return to the model. The next tool request needs a new approval.
ON YOUR MACHINE

Configuration, approvals and backups

Settings reference a credential variable. Originals are backed up before approved writes. No local transcript is written.

Prompt + approved
tool results
AT YOUR CHOSEN ENDPOINT

Model requests and responses

Approved file content can reach your provider. Its retention policy and charges apply. Local tooling does not mean local inference.

02 / GET STARTED

One CLI.
Your exact configuration.

Use your existing Niral installation and Node 22 or newer. No separate DI package or Niral Cloud account is required.

  1. 01

    Choose your provider

    Run setup. Choose OpenAI, Claude, Azure OpenAI or Custom, then enter your exact model or deployment.

  2. 02

    Keep the credential private

    Enter the environment variable name, never the key. Supply its value privately through your terminal or credential manager. DI does not load .env files.

  3. 03

    Check, then start a task

    Status runs offline. Begin with a read-only question to understand the project and review each requested read.

YOUR TERMINAL

Configure the provider

niral di setup

Check settings without an API request

niral di status

Ask about an existing app

niral di ask "Explain this project's routes" --root ./myapp --read-only

Already installed through npm? The existing launcher also accepts npx niral di setup.

Your provider, without substitutions.

Protocol
Responses
Authentication
Bearer token
Model
Your exact model name
API base
https://api.openai.com/v1

The preset supplies the protocol, API base and authentication. You choose the model and credential variable.

No endpoint probing, model fallback or automatic provisioning. Compatible endpoints must support the chosen protocol and function calling. Amazon Bedrock is not currently supported.

03 / COMMAND REFERENCE

From the first question
to the next change.

Five commands, with workspace, read-only and prompt-only modes. DI never starts a server, installs dependencies or deploys your app.

Configure

Choose your provider

niral di setup

Interactive provider setup. Saves settings and the credential variable name, never the key. No API request is made.

Inspect

Check local settings

niral di status

Offline configuration and credential-availability checks, without printing the credential.

Understand

Read without writing

niral di ask "Explain this project's routes" --root ./myapp --read-only

One bounded run with listing and reading tools only. Every tool still requires your approval.

Change

Make a reviewed edit

niral di ask "Add a contact page" --root ./myapp

Inspect files, review proposed full contents, and approve individual writes. Existing files are checked for changes before replacement.

Continue

Work conversationally

niral di chat --root ./myapp

Retains up to eight user/assistant exchanges and 32 KiB of text context in memory. /clear resets context; /exit leaves the session.

Create

Start from a template

niral di new myblog "Customize the home page" --template blog

Confirms before scaffolding a new or empty directory. Templates: minimal, blog and dashboard. The scaffold survives a later model failure.

Prompt

Run without workspace tools

niral di ask "Explain server blocks" --no-tools

Sends only your explicit prompt. This is the supported noninteractive mode; no workspace content is attached automatically.

04 / ACCESS AND CONTROL

Small tool surface.
Explicit boundaries.

There is no auto-approve option, shell execution or delete tool. Every requested operation is validated, authorized and executed sequentially.

100 entries

list_files

One visible directory at a time. No recursive workspace scan.

24 KiB

read_file

UTF-8 source/text content and its SHA-256 hash, only after approval.

24 KiB

write_file

Full-content create or replace. Existing files require the current read hash.

AN APPROVED WRITE
  1. ReadCapture current hash
  2. ReviewApprove full new content
  3. CheckReject stale file edits
  4. Back upPreserve the original
  5. WriteTemporary file + rename

What stays outside the tool surface

Paths outside the workspace, dot paths, conventional data, dependency, build, backup and secret paths, symlinks, hard-linked reads/writes, binary files and unsupported extensions. NIRAL_HOME is excluded too.

Supported: .niral, .js, .mjs, .cjs, .ts, .jsx, .tsx, .css, .html, .md, .json, .txt and .sql.

What still needs your judgment

Gitignore rules are not interpreted. Secrets embedded in ordinary source can still be disclosed through an approved read. Path and hash checks are guardrails, not an OS sandbox or a prompt-injection defense.

Approval shows full replacement content, not a computed diff. Cancellation stops pending work; it does not undo completed edits.

8default model turns
32default tool-call budget
5 mindefault whole-run timeout
32 KiBmaximum prompt

05 / THE DETAILS

Know what happens next.

Where are settings and backups stored?

Settings live in NIRAL_HOME/di.json, defaulting to ~/.niral/di.json, with mode 0600. Only provider settings and the credential variable name are stored. App-side NIRAL_AI_* settings are separate.

Before a write, original content, absolute path and hash are saved under NIRAL_HOME/di-backups/<run-id>/. New files have a null original. Backups are retained without pruning; restore manually after reviewing subsequent changes.

Can I configure DI noninteractively?

Yes. Supply explicit settings. Replace these endpoint and model placeholders with your provider's exact values; the credential itself stays out of arguments.

niral di setup --protocol responses --base-url https://your-provider.example/v1 --model YOUR_EXACT_MODEL --auth bearer --key-env NIRAL_DI_API_KEY

The API base excludes the final /responses, /chat/completions or /messages operation path and query parameters. Use --api-version VERSION when needed. Existing configuration requires --replace. Ctrl-C or end-of-input cancels interactive setup without saving.

Does DI run checks or roll back changes?

No. Review changes, then run niral check, niral test and niral build yourself. There is no automatic test run, dependency installation, rollback, deployment or retry. A failed or cancelled run may already have completed approved edits.

Is the conversation saved or streamed?

Responses are completed, non-streaming responses. Chat keeps a bounded text history in memory; file results are not automatically retained across runs. No local transcript is written. Provider retention and charges follow your chosen provider's policies; Responses store:false is not a general retention guarantee.

What provider compatibility is verified?

Deterministic mocked tests cover protocols, approvals, filesystem boundaries and the CLI. A separate live Azure Responses smoke test verified a basic two-turn, authorized tool round trip on one selected deployment. That is not proof of every model, provider or protocol feature. Streaming and broader live-provider checks remain future work.

What are the provider and agent limits?

The agent defaults to 8 turns, 32 tool calls, 64 KiB of tool results and a 300-second whole-run timeout. Denied calls still consume the budget. The last allowed turn cannot execute tools because no turn would remain to interpret the results.

Provider defaults are 4,096 output tokens, a 120-second request/body timeout, a 2 MiB serialized request limit and a 4 MiB response limit. Truncated, malformed or unsupported responses are errors, not executable tool requests. There are no automatic retries.

Can developers use the provider and agent APIs directly?

The framework exposes createProvider in src/di/provider.js and runAgent in src/di/agent.js. Providers accept explicit configuration and return content, structured tool calls, usage and protocol-specific continuation state. Preserve that state intact between requests within the same protocol.

A host supplies tool schemas, mandatory validators and executors. Authorization must return exactly true. The loop validates the whole batch before executing any call; unknown tools, repeated IDs, malformed arguments and exceeded budgets stop the run. Schemas are not permissions.

Custom hosts must provide their own confinement, backups and disclosure controls. Cancellation is cooperative; in-process work cannot be forcibly rolled back. The CLI model is instructed to inspect applicable AGENTS.md files, but instructions never replace approval.

Provider and host API reference

Part of Niral. Separate from your app runtime.

Explore the full CLI reference and start with a project you know.

CLI reference