npm - ucode-agent - Versions diffs - 1.0.0 - Mend

ucode-agent 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +240 -0
package/package.json +54 -0
package/skills/build-app/SKILL.md +81 -0
package/skills/code-review/SKILL.md +36 -0
package/skills/debug/SKILL.md +47 -0
package/skills/ui-ux/SKILL.md +237 -0
package/skills/write-tests/SKILL.md +47 -0
package/src/core/failure.js +70 -0
package/src/core/history.js +278 -0
package/src/core/loop.js +1146 -0
package/src/core/provider.js +740 -0
package/src/core/skills.js +165 -0
package/src/core/window.js +127 -0
package/src/tools/files.js +466 -0
package/src/tools/index.js +394 -0
package/src/tools/search.js +192 -0
package/src/tools/shared.js +343 -0
package/src/tools/shell.js +553 -0
package/src/tools/web.js +96 -0
package/src/ui/markdown.js +64 -0
package/src/ui/plain.js +325 -0
package/src/ui/screen.js +1067 -0
package/src/ui/theme.js +256 -0
package/ucode.js +118 -0

package/README.md ADDED Viewed

@@ -0,0 +1,240 @@
+# ucode
+A coding agent that lives in your terminal. It reads your code, edits it, runs
+your commands, and keeps every conversation on disk. It runs on NVIDIA and
+Cohere models through OpenRouter, all of them free.
+```
+╭──────────────────────────────────────────────────────────────────────────────────╮
+│  ██╗   ██╗ ██████╗ ██████╗ ██████╗ ███████╗   dir      ~/projects/notes-app      │
+│  ██║   ██║██╔════╝██╔═══██╗██╔══██╗██╔════╝   keys     /help · esc interrupts    │
+│  ██║   ██║██║     ██║   ██║██║  ██║█████╗                                        │
+│  ██║   ██║██║     ██║   ██║██║  ██║██╔══╝                                        │
+│  ╚██████╔╝╚██████╗╚██████╔╝██████╔╝███████╗                                      │
+│   ╚═════╝  ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝   made with ❤️ by om dixit           │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+● Writing index.html
+  └ created · 148 lines
+       1 + <!doctype html>
+       2 + <html lang="en">
+       3 +   <head>
+         … 145 more lines
+● Running npm test
+  └ exit 0 · 12 lines
+╭──────────────────────────────────────────────────────────────────────────────────╮
+│ › now add a dark mode toggle                                                     │
+│                                                                                  │
+│ ◆ Build · Nemotron 3 Ultra (free)                                             4% │
+╰──────────────────────────────────────────────────────────────────────────────────╯
+```
+The status sits inside the input box because it describes the thing you are
+typing into. Three facts, no more: the live mode, the answering model, and how
+full the context window is. The percentage turns amber at 75%, which is where
+older turns start being folded into a summary. While a turn is running the
+middle of that row carries the spinner and the way out of it, and hands the
+space straight back when it finishes.
+## Install
+```bash
+npm i -g ucode-agent
+```
+Then put a key where it will survive upgrades:
+```bash
+mkdir -p ~/.ucode
+echo "OPENROUTER_API_KEY=sk-or-..." > ~/.ucode/.env
+```
+Keys are free at [openrouter.ai/keys](https://openrouter.ai/keys). A `.env` in
+the project you are working on wins over that one, and a real environment
+variable wins over both.
+Then, in any project:
+```bash
+ucode
+```
+Needs Node 22 or newer.
+## The models
+Five, and no picker full of names nobody recognises. NVIDIA and Cohere both
+serve capable models free through OpenRouter, and both handle tool calling
+properly, which is the thing an agent actually depends on.
+| Model | Context | For |
+| --- | --- | --- |
+| **Nemotron 3 Ultra** ★ | 1M | the default — deepest reasoning, slowest to first token |
+| Nemotron 3.5 Lightning | 1M | the same enormous window, answers much sooner |
+| Nemotron 3 Super | 262k | strong all-rounder, quick to start |
+| Nemotron 3 Nano Omni | 256k | small, fast, reasoning tuned |
+| **North Mini Code** ★ | 256k | code and UI specialist — reach for it on frontend work |
+`/model` shows them and switches. `ucode -m cohere/north-mini-code:free`
+starts on one.
+Ultra is the default because the work this is for — read a codebase, hold it in
+mind, change several files consistently — is what a million-token window and a
+long think are for. When the wait stops being worth it, switch.
+## What it does
+**Twelve tools.** `read_file`, `read_files`, `write_file`, `batch_write`, `edit_file`,
+`multi_edit`, `list_dir`, `glob`, `grep`, `run_command`, `run_commands`,
+`web_search`. Read-only calls run in parallel; anything that writes runs on its
+own, in order.
+**Edits that never guess.** `edit_file` matches exactly once or it fails, and
+when it fails it says *why* — the text is there but the indentation differs, or
+its first line appears at line 40 and the rest does not. A wrong edit reported
+as a success is the most expensive thing an agent can do.
+**Diffs with real line numbers.** Removed lines are numbered where they were,
+added lines where they now are. Numbers you can jump to, not decoration.
+**Live commentary.** `● Listing src`, `● Running npm test` — what it is doing,
+as it does it, named after the file or command rather than the tool.
+**Two modes.** Build edits and runs. Plan reads and researches with the writing
+tools withheld, which is stronger than asking a model nicely. `ctrl+b` swaps
+them; the chip inside the input box says which is live.
+**Sessions.** Everything is on disk under `~/.ucode/sessions`, saved after every
+step. `/resume` lists them with what each one was actually about, the ones from
+this folder first.
+**A context window that folds rather than forgets.** Past 75% the oldest turns
+are summarised instead of dropped, never cutting between a tool call and its
+result. The full history stays on disk regardless.
+**Screenshots.** Mention a `.png` in your message and it gets attached.
+## Skills
+A skill is a folder with a `SKILL.md`: frontmatter, then instructions. Only the
+names and one-line descriptions go into the system prompt — a body is pulled in
+when it is wanted, so the prompt stays the same size however many you add.
+| Skill | For |
+| --- | --- |
+| `ui-ux` | interfaces: direction, tokens, layout, states, motion, accessibility |
+| `build-app` | going from nothing to something running, and proving it runs |
+| `debug` | finding the real cause instead of the first plausible one |
+| `code-review` | reviewing a change the way a careful colleague would |
+| `write-tests` | tests that fail for the right reason |
+**`ui-ux` loads itself.** Ask for an app, a dashboard, a landing page, or say
+the UI is ugly, and the whole skill is in context before the model takes its
+first step. Waiting for the model to decide it needs design guidance means
+finding out it did not after the app is built.
+Add your own in `.ucode/skills/<name>/SKILL.md` inside a project. A project
+skill shadows a built-in of the same name. Give it an `auto:` line and it loads
+itself too:
+```markdown
+---
+name: house-style
+description: How we write services here.
+auto: endpoint, handler, migration
+---
+Everything after the frontmatter is the instruction.
+```
+## Commands
+| | |
+| --- | --- |
+| `/help` | the list |
+| `/model` | show the models and switch — `/models` does the same |
+| `/resume` | pick up an earlier conversation — `/session`, `/sessions` too |
+| `/new` | save this one and start fresh |
+| `/skills` | what it knows how to do, and what is loaded |
+| `/search <query>` | look something up on the web |
+| `/copy` | last reply to the clipboard |
+| `/clear` | clear the screen, keep the conversation |
+| `/exit` | save and quit |
+`ctrl+b` plan/build · `esc` stops a running turn · `ctrl+d` quits ·
+`↑ ↓` scroll the conversation, or walk history once you are typing ·
+`tab` completes a command
+## Options
+```
+ucode [options]
+  -m, --model <id>   which model to use
+  -C, --cwd <dir>    work in another directory
+      --plan         start in plan mode
+      --debug        print stack traces when something breaks
+  -v, --version      print the version
+  -h, --help         the above
+```
+## Configuration
+| | |
+| --- | --- |
+| `~/.ucode/.env` | `OPENROUTER_API_KEY`, and `TAVILY_API_KEY` for web search |
+| `~/.ucode/sessions/` | one JSON per conversation |
+| `.ucode/skills/` | skills belonging to a project |
+Environment overrides: `UCODE_MODEL`, `UCODE_MAX_CONTEXT_TOKENS`,
+`UCODE_MAX_STEPS`, `UCODE_MAX_TOOL_OUTPUT`, `UCODE_REQUEST_TIMEOUT_MS`,
+`UCODE_BASE_URL`.
+Web search needs a Tavily key — free, 1000 searches a month, no card. Without
+one, ucode answers from what it knows and says that it could not check.
+## How it is put together
+```
+ucode.js              the command: arguments in, Agent out
+src/core/loop.js      the agent loop, the system prompt, the slash commands
+src/core/provider.js  the only file that knows OpenRouter exists
+src/core/history.js   sessions on disk
+src/core/window.js    folding a long conversation to fit
+src/core/skills.js    loading skills, and deciding which load themselves
+src/core/failure.js   one error shape: what, why, what next
+src/tools/            the eleven tools, plus their shared plumbing
+src/ui/screen.js      the full-screen interface
+src/ui/plain.js       the same interface for when there is no terminal
+src/ui/theme.js       colour, boxes, and the string maths behind both
+```
+Everything above `provider.js` speaks one small provider-neutral message
+format. Moving to another host means rewriting that one file.
+Every failure carries three things — what was attempted, what failed, and what
+to do next — so no screen ever has to fall back on a stack trace. Tool failures
+are handed to the model as text instead, which is why they read like
+instructions.
+## Development
+```bash
+git clone https://github.com/sppideey/ucode-agent
+cd ucode-agent
+npm install
+npm link      # puts `ucode` on PATH, pointing at this checkout
+npm test
+```
+`npm link` matters while developing: it symlinks the global command to your
+working copy, so an edit is live on the next launch. Running
+`npm i -g ucode-agent` replaces that with a frozen copy from the registry and
+your edits stop taking effect.
+The tests need no network and no framework — `node test/run.js` runs them all.
+## Licence
+ISC. Made with ❤️ by om dixit.

package/package.json ADDED Viewed

@@ -0,0 +1,54 @@
+{
+  "name": "ucode-agent",
+  "version": "1.0.0",
+  "description": "ucode - a terminal coding agent that reads, edits and runs your code. NVIDIA and Cohere models over OpenRouter.",
+  "type": "module",
+  "main": "ucode.js",
+  "bin": {
+    "ucode": "ucode.js"
+  },
+  "files": [
+    "ucode.js",
+    "src/",
+    "skills/"
+  ],
+  "scripts": {
+    "start": "node ucode.js",
+    "test": "node test/run.js",
+    "prepublishOnly": "node test/run.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/sppideey/ucode-agent.git"
+  },
+  "bugs": {
+    "url": "https://github.com/sppideey/ucode-agent/issues"
+  },
+  "homepage": "https://github.com/sppideey/ucode-agent#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent",
+    "cli",
+    "terminal",
+    "coding-agent",
+    "llm",
+    "nvidia",
+    "nemotron",
+    "cohere",
+    "openrouter"
+  ],
+  "author": "om dixit",
+  "license": "ISC",
+  "dependencies": {
+    "chalk": "^6.0.0",
+    "dotenv": "^17.4.2",
+    "marked": "^15.0.12",
+    "marked-terminal": "^7.3.0",
+    "openai": "^7.4.0"
+  }
+}

package/skills/build-app/SKILL.md ADDED Viewed

@@ -0,0 +1,81 @@
+---
+name: build-app
+description: Take something from nothing to running — choosing the stack, laying out the files, installing, wiring it up, and proving it works before saying it does.
+auto: scaffold, new project, from scratch, build an app, make an app, create an app, build a website, make a website, build a site, build me a, next.js app, nextjs app, next app, react app, vite app, shadcn, create-next-app
+---
+# Building something from nothing
+The failure mode here is not writing bad code. It is delivering a folder of
+files that has never been run, described as if it works.
+## Decide the shape before writing anything
+State these in one line each, out loud, then build to them:
+- **What it does** — the single sentence a user would say.
+- **The stack** — and why. Default to the smallest thing that does the job: a
+  single HTML file with no build step is a legitimate answer and often the
+  right one. Reach for a framework when routing, state or a component tree
+  genuinely earns it, not because the project sounds serious.
+- **The files** — the whole list, before you create any of them.
+If the request has a user interface in it, the `ui-ux` skill is already loaded.
+Follow it. Do not design as you go and tidy up afterwards.
+## Scaffold without being asked questions
+Nothing you run has a keyboard. A scaffolder that stops to ask "Would you like
+to use TypeScript?" gets no answer and fails, so give it every answer up front:
+```bash
+# Next.js — creates ./my-app; use . instead of a name to fill the current folder
+npx create-next-app@latest my-app --ts --tailwind --eslint --app --src-dir --import-alias "@/*" --use-npm --yes
+# shadcn/ui, from inside the Next.js project
+npx shadcn@latest init -d -y
+npx shadcn@latest add button card input label badge progress separator skeleton sonner -y
+```
+For any other scaffolder, find its flags for every question it would ask
+(`--help` lists them) before running it for real.
+`create-next-app` refuses a folder that already has files in it. If the current
+folder is not empty, scaffold into a named subfolder and pass that as `cwd` to
+every command after it.
+Add every shadcn component you will need in one `add` call, not one per call.
+## Lay it out in one pass
+Use `batch_write` for the whole skeleton rather than `write_file` twenty times.
+One call, every file, in dependency order. Then `run_command` the install, and
+`run_commands` for anything independent that can happen at the same time.
+Real content from the first pass. Placeholder copy, `TODO`, and a commented-out
+function are all the same thing: a promise you did not keep, in a file the user
+now has to find.
+## Wire everything
+Every button does its thing. Every form submits, validates and says what went
+wrong. Every list has an empty state. Every request has a loading state and a
+failure state. A control that does nothing is worse than no control, because
+the user has to try it to find out.
+If it stores anything, decide where, and make it survive a reload.
+## Run it, then look at it
+- Start it with `run_command`. A dev server needs `background: true`, which
+  returns immediately with a PID — a foreground server just burns the turn and
+  gets killed.
+- Then actually exercise it: `curl` the routes, run the tests, open the page.
+  A clean build is not evidence that it works, only that it compiles.
+- Fix what you find and run it again.
+## Report what happened
+Say what you built, how to start it, and what you checked. If something is
+untested or unfinished, say which part and why — that sentence costs you
+nothing and saves the user an hour of finding out on their own.

package/skills/code-review/SKILL.md ADDED Viewed

@@ -0,0 +1,36 @@
+---
+name: code-review
+description: Review a change the way a careful colleague would — correctness first, then the things that will hurt later, with the reasoning attached.
+---
+# Reviewing code
+A review that lists everything is not a review, it is a linter with opinions.
+Rank what you find, and be honest about which parts you actually verified.
+## Read it in this order
+1. **Correctness.** Does it do what it claims? Walk the edge cases: empty,
+   one, many, null, the boundary value, the concurrent call, the second run.
+2. **Failure.** What happens when the thing it depends on fails? A swallowed
+   error and a bare `catch {}` are bugs waiting for the worst possible moment.
+3. **Security.** Untrusted input reaching a query, a shell, a path, or the DOM.
+   Secrets in the source. Credentials in a log line.
+4. **Contracts.** Did a signature, a return shape or a stored format change
+   without every caller and every existing row being accounted for?
+5. **Clarity.** Names that say what the thing is. Comments that explain why,
+   never what. A function that fits in your head.
+6. **Tests.** Does the test actually fail when the code is wrong? A test that
+   asserts a mock was called proves nothing about behaviour.
+## Say it usefully
+For each finding: the file and line, what breaks, and the input that breaks it.
+"This could be cleaner" is not actionable. "`parse()` throws on an empty body,
+which the retry path hits on a 204" is.
+Separate what you know from what you suspect, and say which is which. If you
+did not run it, do not describe the behaviour as if you watched it happen.
+Say what is good, briefly, and only where it is genuinely worth copying.
+Reviews that never approve of anything stop being read.

package/skills/debug/SKILL.md ADDED Viewed

@@ -0,0 +1,47 @@
+---
+name: debug
+description: Find the actual cause of a bug instead of the first plausible one — reproduce it, narrow it, prove the fix, and leave a test behind.
+---
+# Debugging
+The temptation is to read the code, form a theory, change something, and
+declare victory when the symptom disappears. That is how a bug gets moved
+rather than fixed.
+## Reproduce it first
+Do not start from the description. Run the thing and see the failure with your
+own eyes: the command, the input, the exact error and where it comes from. If
+you cannot reproduce it, say so and ask for what you need — the input, the
+version, the full stack. Guessing from a paraphrase wastes everyone's turn.
+## Narrow before you theorise
+- Read the whole stack trace, including the frames you assume are irrelevant.
+  The top frame is where it surfaced, not necessarily where it went wrong.
+- `grep` for the message text to find where it is produced.
+- Cut the search space in half at a time: does the smaller input fail? Does it
+  fail on the previous commit? Does the layer below get the right value?
+- Print or log the values at the boundary rather than reasoning about what they
+  should be. What you believe is in that variable is the thing under suspicion.
+## Fix the cause
+State the cause in one sentence before you change anything: *this value is
+undefined here because the caller only sets it on the success path*. If you
+cannot write that sentence, you have not found it yet.
+Then fix that, not the symptom. A guard that hides the undefined value leaves
+the real defect in place, with one more layer over it.
+## Prove it
+- Run the original reproduction. It must now pass.
+- Run the rest of the tests. A fix that breaks two other things is a trade,
+  and the user gets to make it, not you.
+- Write a test that fails without your fix. A bug with no regression test comes
+  back.
+Then say what the cause actually was, in one or two sentences. If you fixed
+something adjacent along the way, say that too.