Kritya

kritya

Dependency risk is scanned on Socket; see SECURITY.md for how flagged findings are triaged.

⚠️ Beta — APIs, flags, and behavior may still change between releases.

Open source, MIT licensed.

GitHub is the canonical repo; the GitLab copy is a read-only backup mirror.

Superintelligence at your command line

It works with any OpenAI-compatible endpoint: build.nvidia.com (Qwen3 Coder, Kimi K3, DeepSeek, GLM, Nemotron, ...) by default, plus OpenAI, OpenRouter, Groq, DeepSeek, Mistral, Together, and local models via Ollama.

Works on Linux, macOS, and Windows.

Configured for OpenAI-compatible endpoint - used with build.nvidia.com; other providers are wired the same way but not exercised.

cd your-project
kritya .

The agent can read, write, and edit files, search code, and run shell commands — autonomously looping until your request is done. Anything that mutates state (writes, edits, shell commands) asks for your permission first.

Features

• Provider-agnostic — OpenAI-compatible endpoint (NVIDIA, OpenAI, OpenRouter, Groq, DeepSeek, Mistral, Together, Ollama, ...); tested with NVIDIA only
• Permission-gated actions — every file write/edit/shell command asks first, with configurable allow/deny rules
• Sandboxed execution — OS-enforced backstop (bwrap/sandbox-exec) confining writes to the workspace; falls back to unsandboxed (with a warning) if the sandbox binary isn't installed
• Staged project workflow — /flow-brainstorm → spec → plan → build → review → fix → ship for building something new end-to-end, with parked projects you can pick up again later
• MCP + Agent Plugins support — extend with external tools/servers, each individually trust-gated
• Undo/redo/checkpoints — revert or rewind file changes and conversation state
• Office docs & notebooks — read/write Word, Excel, PowerPoint, PDF, Jupyter
  • Headless/CI mode — scriptable, no-TTY runs for automation
  • Privacy mode — --privacy, KRITYA_PRIVACY=1, or "privacyMode": true disables transcript, audit, and telemetry persistence

Setup

Requires Node.js >=22.23.4.

1. Get an API key from your chosen provider (click any model → "Get API Key").

2. Set it (any one of these):

   • Put NVIDIA_API_KEY=nvapi-... in a .env file — checked in the workspace you launch in, and ~/.kritya/.env
   • Linux/macOS: export NVIDIA_API_KEY=nvapi-...
   • Windows: setx NVIDIA_API_KEY nvapi-... (then open a new terminal)

   Skip this and kritya will prompt for the key on first launch (interactive mode only) and save it to ~/.kritya/.env for you.

   Optional: add TAVILY_API_KEY the same way to enable the agent's web-search tool (/web-search) — get one at tavily.com.

   Optional (Linux): install bubblewrap (bwrap) for OS-level command sandboxing — macOS has its sandbox built in; without bwrap, Linux falls back to running commands unsandboxed with a warning.

3. Install and run — pick one:

# Option A: npm
npm install -g kritya@beta
cd ~/some-project
kritya               # enter

# Option B: from source
git clone https://github.com/GenAICloudDevOps/Kritya.git
cd Kritya
npm install
npm run build
npm link           # puts `kritya` on your PATH
cd ~/some-project
kritya               # enter

Desktop app

There is also an Electron desktop app wrapping the same agent (electron/, npm run electron:dev / npm run electron:build). Automatic desktop builds are currently paused; Windows installers are built manually via the "Build Desktop App" workflow. See docs/ARCHITECTURE.md for how the app is put together.

Screenshots

One-time AI disclosure notice on first launch

Startup banner with model and workspace status

Permission prompt for a web search request

Command list shown after typing /

Test suite and coverage output

Usage

kritya [directory] [options]

  -c, --continue        resume the most recent session for this directory
  -r, --resume [name]   list past sessions, or resume one by its auto-derived
                        name (e.g. `kritya -r fix-login-bug`) or 5-character
                        code; plain `-r` opens the list
  -m, --model <id>      use any model ID your provider offers
  -p, --provider <name> nvidia (default), openai, openrouter, groq, deepseek,
                        mistral, together, ollama, switchyard (multi-model
                        routing via NVIDIA NeMo Switchyard), or a custom one
  -h, --help            help
  -v, --version         version

Subcommands — these run instead of starting a session:

kritya doctor [dir] [--json] [--offline]
                      check that this installation is set up correctly: the
                      Node version against the package's engines, the config
                      file, the active provider and whether its API key
                      resolves *and* the endpoint accepts it, workspace trust
                      and git state, MCP servers (including unset ${VAR}s),
                      sandbox availability, persistence settings, skills and
                      hooks, and whether a newer release exists
kritya audit ...      inspect the local audit log (see docs/CONFIGURATION.md)
kritya skills ...     list and validate discovered skills

kritya doctor exits non-zero only when something is actually broken; the warnings it prints are "this works, but not the way you may expect" — an unavailable sandbox, an untrusted workspace, a lagging latest tag.

In-session commands (type / to see them with autocomplete; letters filter the list):

Command	What it does
/model	interactive model picker (/model <id> sets any model ID directly)
/provider	list providers, or /provider <name> to switch mid-session (more)
/flow-brainstorm <idea>	start the staged new-project workflow (see below)
/flow-spec	project workflow: write the spec from the approved brainstorm
/flow-plan	project workflow: plan from the spec (read-only)
/flow-build	project workflow: implement the plan, with tests
/flow-review	project workflow: spec-compliance and security review of the build
/flow-fix	project workflow: fix the review's findings, each one re-verified
/flow-ship	project workflow: hand over the finished project, with the test suite actually run
/flow	continue the workflow from wherever the project stands
/flow-back <phase>	rewind to a phase and re-run everything after it (bounded — see below)
/plan	toggle plan mode: /plan, /plan on, /plan off (unrelated to /flow-plan)
/project	workflow status; list, resume <name>, goto <phase>, rename <name>, clear
/diff	show the cumulative git diff of this session's changes
/init	scan the repo and generate a KRITYA.md project-memory file
/commit	have the agent review, stage, and commit the current git changes
/pr	push the branch and open a GitHub PR: /pr [--draft] [--title T] [--body B] [--base BR]
/summarize	one-shot summary of the session so far (history is left untouched)
/template	prompt templates: list, /template [words], /template save|delete
/web-search <query>	search the web via Tavily; results are shown and added to context
/mcp	MCP server status; /mcp add|remove <name>, /mcp login|logout <name>, /mcp trust (more)
/skills	list discovered skills (project + user-global) and why any were skipped
/plugins	list discovered Agent Plugins, what each contributes, and why any were skipped (more)
/undo	revert all file changes from the agent's last turn
/redo	reapply the change most recently undone
/checkpoint <name>	save a named point in the session (/checkpoint alone lists saved ones)
/rewind <name>	rewind both the conversation and the files to a checkpoint
/rename <name>	rename this session (/rename alone shows the current name)
/export [path]	export the transcript to markdown (default: kritya-<name>-<stamp>.md)
/compact	summarize older conversation to free context space
/clear	start a fresh conversation
/cost	token usage and estimated $ (see Pricing below)
/audit	show this session's permission decisions and verify the audit log's chain (more)
/budget	show session token budget; /budget reset or /budget <number>
/status	show context/budget/token/task detail left off the always-visible status line
/kill	emergency stop: /kill [reason] halts everything; /kill off releases
/help	command list
/exit	quit

Custom /commands you define (see docs/CONFIGURATION.md) also appear here.

Esc cancels a running request. ↑/↓ recalls input history. Ctrl+O toggles full tool output. Ctrl+E opens the file the agent touched most recently in $EDITOR. Ctrl+P opens the command palette (fuzzy-find commands and checkpoints). Ctrl+B copies the agent's most recent code block. Ctrl+R opens reverse history search. Ctrl+K is the kill switch (see below). Ctrl+C exits.

More features

• Staged new-project workflow — ask kritya to build something new (a FastAPI backend, a Next.js frontend, a CLI) and it doesn't dive straight into code. It runs seven phases — brainstorm → spec → plan → build → review → fix → ship — writing a durable artifact for each under docs/<name>/ and stopping for your approval between phases:

  Phase	Produces
  brainstorm	brainstorm.md — problem, users, MVP features, stack
  spec	spec.md — contracts, data schema, acceptance criteria (MUST/LATER), and non-functional requirements (security/reliability/performance/CI, asked about via ask_user — skipped if none apply)
  plan	plan.md — architecture and ordered milestones, each tagged RISKY or ROUTINE, plus trust boundaries for any security/reliability requirement
  build	the code, with tests written before the code they test, plus negative/failure-path tests for security/reliability-tagged milestones, and a live milestone checklist
  review	review.md — a one-line scorecard, then spec-compliance, security, and reliability findings
  fix	fix.md — the review's findings addressed and re-verified
  ship	ship.md — a handover summary, the test suite actually run, and an optional commit

  Spec comes before plan on purpose: the spec settles what (and pins the numbered acceptance criteria everything downstream is held to), the plan settles how and sequences milestones against those criteria. Each phase reads only the artifact immediately before it, so nothing gets re-derived. The agent walks the phases on its own, or you drive them by hand with /flow-brainstorm <idea>, /flow-spec, /flow-plan, /flow-build, /flow-review, /flow-fix, /flow-ship — and after each one kritya tells you which command comes next, so the handoff doesn't depend on the model remembering to say it.

  Where it stops is a policy, not a property of the phase list. It hands back for approval after brainstorm, spec and plan — the phases where changing course is still cheap — then runs build through ship as one stretch, because by then the work is already done and "shall I now review what I just built?" adds a round trip without adding a decision. /flow continues from wherever the project stands; --auto runs the rest without stopping, --until <phase> stops at a named phase, and --fast merges brainstorm and spec into one stretch. A phase refuses to run if the artifact it reads was never written (--force overrides). /flow-fix only fixes what review found; if anything is still open afterward it tells you to run /flow-review again, /flow-fix again, or /flow-back <phase> if the finding is really a problem with the requirement — that rewinds to a phase and re-runs everything after it, bounded at two passes so a disagreement the model can't resolve can't spend forever.

  Parking a project keeps its phase. Starting a second project used to overwrite the first's place in the flow, because .kritya/project.json only ever holds the active one. A registry at .kritya/projects.json now keeps every project the workspace has run, so /project list shows them all and /project resume <name> picks one up exactly where it stopped — phase, loop-back budget and all. /project clear ends the active workflow but parks rather than forgets it, and a new /flow-brainstorm names the way back.

  A gate doesn't cost you a file read. Each phase records a one-line scorecard, so /project shows what every phase concluded ("6 ACs, 2 MUST") instead of just a generic description — you can judge whether to approve without opening anything. When a project is active, launch names its phase, and after a gated phase /flow is prefilled into the input line: Enter continues, Esc (or any edit) discards it. The gate still holds — nothing runs until you submit.

  While a workflow is active the statusline carries a ⚑ name N/7 phase flag and the spinner names the running phase. /project shows the full picture, including a warning if an earlier artifact was edited after a later one already depended on it.

  The project is named from your idea unless you name it yourself with a short prefix — /flow-brainstorm reverser: a script that reverses a string gives you docs/reverser/. /project rename <name> moves an existing one.

  Cost matters here — seven phases in one session adds up — so kritya compacts the conversation at each phase boundary (the artifact is on disk, so the transcript that produced it is redundant), caps artifact length, and in the build phase dispatches independent milestones to isolated write subagents rather than pulling every file into the main context. The review phase runs its three reviewers as read-only subagents, so only their findings come back; the fix phase does the same to re-verify only what it changed.

  In the plan phase, plan mode's read-only guard is relaxed just enough to let the agent write Markdown under that project's own docs/<name>/ folder — other docs, application code, and shell stay blocked until you /flow-build. Plan mode itself is still a separate, general-purpose toggle — /plan, /plan on, /plan off — unrelated to the workflow's /flow-plan phase.

• Trust levels — Shift+Tab cycles normal (every write/edit asks first) → accept-edits (file writes/edits auto-approve, no prompt) → dry-run (read-only: the agent explores and proposes a plan; edits and shell are blocked) → auto (EVERY tool call auto-approves, including destructive shell commands — nothing asks first) → back to normal. Auto mode is only offered when the sandbox is active, and the sandbox — not a human — is what contains any damage it causes; with the sandbox off, dry-run goes straight back to normal. In accept-edits mode, destructive shell commands (rm -rf, force-push, etc.) still prompt — that guard only turns off in auto mode. The statusline always shows which mode you're in, with a running (N auto-approved) count in the auto-approve modes so you know how much slipped through before checking /diff. The first time you switch into accept-edits or auto mode each session, kritya asks you to confirm first so it's a deliberate choice, not an accidental keypress. /plan on and /plan off set plan mode explicitly; a bare /plan toggles it. Plan mode is separate from this cycle. /plan never touches the project workflow — that's /flow-plan.

• Kill switch — Ctrl+K (or /kill [reason]) is a hard stop for the whole session. It aborts the in-flight model stream, any running tool, and every subagent at once, then refuses everything afterwards: new messages, tool calls, compaction, and any slash command that would drive the agent all come back with ⛔ Kill switch ACTIVE until you run /kill off. Unlike Esc (which cancels one turn) it outranks every other mode — plan mode, accept-edits, and allow rules cannot get a tool past it — and it works from anywhere, including while a permission prompt is on screen. The statusline shows ⛔ KILLED, and both the stop and the release are written to the audit log. It's session-only: restarting kritya comes up in the normal state. Some terminals steal Ctrl+K for their own shortcuts before kritya ever sees it — VS Code's integrated terminal is the common case, where it's bound as a chord prefix. /kill [reason] always works there instead; to get Ctrl+K itself working, add a terminalFocus-scoped override to VS Code's keybindings.json:

  {
    "key": "ctrl+k",
    "command": "workbench.action.terminal.sendSequence",
    "args": { "text": "\u000b" },
    "when": "terminalFocus"
  }
  

• Subagents — the agent can dispatch one or more focused investigations to fresh contexts at once (spawn_agent), each returning only its findings — keeps the main conversation lean on big searches. It can also dispatch write-capable subagents (spawn_write_agent) for independent chunks of work that can proceed in parallel; each one is isolated on its own git branch/worktree, so its edits and shell commands never touch your real working tree — review the diff and merge the branch yourself when ready. Destructive commands (rm -rf, force push, etc.) are always blocked inside a write subagent, since there's no one there to confirm them; each subagent also has a hard time limit and no more than 6 (read) / 4 (write) run in one call.

• Image attachments — @screenshot.png sends the image to vision-capable models alongside your message.

• Undo / redo — /undo reverts the last turn's file changes; /redo reapplies them. Undo is multi-level. A file watcher also checkpoints edits you make yourself (in your own editor) to any file kritya has touched this session, as their own step in the right order — so hand-editing a file between turns and later running /undo never silently discards that edit.

• Checkpoint / rewind — /checkpoint <name> saves a named point in the session; /rewind <name> rolls both the conversation and the files back to it at once (e.g. "go back to before the auth refactor"), where /undo only steps back file changes one turn at a time. Checkpoints are in-memory for the current session.

• Steer mid-run — type while the agent is working and press Enter; your message is queued and absorbed before its next step (no need to interrupt).

• Auto-compaction → self-improving project memory — when the conversation nears the model's context window (80% of contextWindow, default 120k tokens), older turns are summarized automatically; /status shows current usage as context used: N%. Compaction (auto or manual /compact) also distills durable, objective facts out of what's being summarized away — build/test commands, package manager, conventions actually observed — and merges any new ones into a ## Learned by kritya section in KRITYA.md, deduplicated and capped at 20 facts. Anything you or /init wrote above that section is left untouched. It's scoped to describing the project, not storing instructions, since this file is read back as background context on every future run.

• Token budget — a session-wide cap on combined prompt + completion tokens across every turn and model (default 1,000,000; set tokenBudget in config, or /budget <number> mid-session). The statusline shows budget N% once usage crosses 80% (yellow, with a one-time warning) or the budget is hit (red); /status shows it from the start. It then stops further turns entirely at 100% until you run /budget reset (clears the count) or /budget <number> (raises the cap). /cost also reports it.

• Background processes — the agent can start dev servers/watchers with background: true, read their output (bg_output), and stop them (bg_kill); everything is killed when kritya exits. Foreground commands accept a timeout_seconds (default 120), and long output keeps the tail, where the errors are.

• Git aware — the statusline shows the current branch, the agent sees git status each request, and /undo checkpoints are per turn.

• @ file mentions — type @ in your message to autocomplete a file path (↑↓ select, Tab/Enter attach); the file's content is sent along with your message.

• Project memory — create a KRITYA.md in your workspace root (or run /init to generate one) with standing instructions; the agent reads it every request.

• Sub-task checklist → resumable plans — for multi-step requests the agent plans first and shows a live ☐/◐/☑ checklist as it works, with a compact tasks N/M summary available via /status. The checklist is saved alongside the session, so kritya -c (and picking a session via -r) restores not just the conversation but exactly which steps were done, in progress, or still pending.

• Diff preview — write/edit permission prompts show a red/green line diff of exactly what will change before you approve; code blocks in answers are syntax-highlighted.

• Session search — kritya -r lists past sessions by title (first message); type to filter.

• Web search tool — besides /web-search, the agent can search on its own when it needs current information (needs TAVILY_API_KEY in .env, get one at tavily.com). Web content is delimited as untrusted so pages can't inject instructions into the agent.

• Reading the web, not just searching it — fetch_url pulls the full text of one known URL (docs page, raw file, JSON endpoint), where search only returns snippets; deep_research takes several focused sub-queries, reads the top result pages for each, and returns one consolidated cited bundle for broad comparison questions. Both refuse local and private-network addresses, so neither can be steered at your internal network.

• Office documents and notebooks — read_document/write_document handle Word (.docx), Excel (.xlsx), PowerPoint (.pptx), and PDF, with edit_spreadsheet for targeted cell changes and edit_pdf for page operations (delete, rotate, reorder, extract). Jupyter notebooks get read_notebook/edit_notebook, which work cell-by-cell instead of forcing the agent to rewrite the whole .ipynb JSON.

• Agent Plugins — bundle skills, slash commands, and MCP servers into one versioned folder under .kritya/plugins/ (project) or ~/.kritya/plugins/ (global), so a capability you want everywhere is one folder to copy rather than three things to wire up. /plugins shows what loaded, what each contributes, and why anything was skipped. A workspace plugin only loads once you've trusted that workspace, and any MCP server it declares still needs its own approval (more).

• Prompt-caching awareness — the system prompt is ordered stable-first (identity and rules → project memory → volatile git status/listing last) so providers can reuse their cached prompt prefix across turns instead of re-reading everything. /cost and /status show how many prompt tokens were served from the provider's cache; add an optional "cachedInput" rate to your pricing config to see the dollar savings.

• LSP integration — the agent gets go-to-definition, find-references, hover type info, live diagnostics, and project-wide rename from real language servers (lsp_definition, lsp_references, lsp_hover, lsp_diagnostics, lsp_rename), resolved semantically instead of by text search. lsp_rename renames only the actual occurrences of that symbol — never a same-named but unrelated variable, and never text in comments or strings — and asks for permission like any other mutating tool. Supports TypeScript/JavaScript, Python, Go, Rust, and C/C++ — it uses whichever servers you have installed (typescript-language-server, pyright, gopls, rust-analyzer, clangd) and tells the agent the install command when one is missing. Servers spawn on first use, stay warm for the session, and never require configuration.

Headless / CI mode

Run one prompt to completion with no terminal UI and no TTY requirement — for scripts, CI pipelines, and GitHub Actions:

kritya --prompt "fix the failing tests" --output json

Exits 0 on success, 1 on failure — check $? in a pipeline. --output json prints a single JSON object on stdout: {success, result, error, toolCalls, usage, durationMs, model}. Plain --output text (the default) just prints the agent's final answer.

There's no terminal to show a permission prompt, so headless mode never blocks waiting for one:

• Mutating tool calls are denied by default unless covered by an allow rule in .kritya/settings.json, or --allow-all is passed to approve them all.
• Destructive commands (rm -rf, force-push, etc.) are always denied, even with --allow-all — there's no one to confirm them, so that guard never turns off.
• The workspace's own .kritya/settings.json, hooks, .env, and custom commands only take effect with --trust, or if the workspace was already trusted in a prior interactive session — never silently, since CI often checks out untrusted branches/PRs.
• --timeout <seconds> caps the whole run (default 1800); a stuck turn is aborted rather than hanging a CI job forever.

Example GitHub Actions step:

- name: Fix failing tests with kritya
  env:
    NVIDIA_API_KEY: ${{ secrets.NVIDIA_API_KEY }}
  run: |
    npx kritya --prompt "run the test suite, fix any failing tests, and show a diff" \
      --output json --allow-all > result.json
    cat result.json

Subagents (spawn_agent/spawn_write_agent) aren't available in headless mode — a single prompt/response doesn't need the parallel-dispatch machinery they're built for.

Permissions & Configuration

Permission rules, sandboxing, the audit log and tracing, the config file, provider fallback, custom slash commands, skills, hooks, MCP servers (including OAuth login to hosted servers), and Agent Plugins are all covered in docs/CONFIGURATION.md. The threat model and what each safeguard does and doesn't guarantee are in SECURITY.md.

The short version: mutating tools (write_file, edit_file, shell) prompt for permission unless allowlisted in .kritya/settings.json; destructive commands (rm -rf, force-push, etc.) always prompt regardless, and shell commands are sandboxed by default on Linux/macOS. Provider and model config lives in ~/.kritya/config.json.

Privacy

kritya collects no telemetry and phones home to nothing of its own by default. Network requests go only to the model provider you configure (and to Tavily if you use web search). Sessions and config stay on your machine under ~/.kritya/.

Two things leave the machine beyond the model provider, and both are opt-out:

• The update check. kritya --version and kritya doctor ask the public npm registry for the latest published version, so they can tell you when you're behind. The answer is cached in ~/.kritya/update-check.json for 24 hours, so it is one request per day at most, and it only runs when stdout is a TTY — a script or a pipe never triggers it and never sees the notice. KRITYA_NO_UPDATE_CHECK=1 turns it off entirely.
• Tracing, if you opt in via KRITYA_OTEL_ENDPOINT (see Audit log & telemetry): spans are sent to the OpenTelemetry Collector you point it at — nothing is exported anywhere unless you configure that endpoint yourself.

Development

npm run dev          # run from source (tsx)
npm run build        # compile to dist/ (strict TypeScript)
npm test             # build + unit tests
npm run lint         # eslint
npm run format       # prettier --write

Architecture: src/provider (OpenAI-compatible streaming client) → src/agent (the tool-call loop, compaction, system prompt) → src/tools (plain-object tools) → src/ui (Ink/React terminal UI), with src/permissions, src/trust, src/hooks, src/mcp, src/plugins, src/lsp, src/commands, src/session, src/shell (background processes + sandboxing), src/audit, src/telemetry, and src/git supporting. src/headless.ts and src/engine.ts are the CI entry points onto the same core. See docs/ARCHITECTURE.md for a full tour and CONTRIBUTING.md to get started.

License

MIT.