File tools built for how agents work.

search

Literal by default, regex when asked. One call does what a pipeline of greps would.

• and (several strings on one line) and not (exclusions), with 1 line of context before and 4 after by default.
• Each hit is labeled with its enclosing function or class, and is a handle that reads like a compiler location.
• Modes for spans, files, counts and matches; within narrows an earlier result without losing its handles.
• Skips node_modules, dist, .git, binaries and huge files. Lockfile hits are counted, not listed. A .vegvisirignore tunes the rest.

search({ pattern: "token", not: ["test"], mode: "files" })
3 files · +2 in pnpm-lock.yaml
src/auth/session.ts   4 hits
src/auth/refresh.ts   2 hits
src/api/client.ts     1 hit

definition

The whole body of a function or class, by name, Class.method, or a search hit’s handle.

• A name defined more than once comes back AMBIGUOUS with a handle per definition.

definition("Session.refresh")
h_src/auth/session.ts:42-58:5a10ce3f
  42	  async refresh(): Promise<void> {
  43	    const next = await this.client.renew(this.token)
  …

references

Every use of a name, grouped by kind: definition, import, call, JSX, type, member access, object key and more.

• Matches in comments, strings and docs are counted, not listed.
• Hits are editable sites, so a rename is references followed by editMatches.
• Syntactic, not type-resolved: x.start on an unknown receiver is reported as member access.

references("loadCart")
definition   1  src/cart/load.ts:12
import       3  src/api/checkout.ts:4 …
call         5  src/api/checkout.ts:35 …
+2 in comments and docs

outline

A file’s shape without its bodies: imports, then declarations nested under their containers, with signatures and the first line of each doc comment.

• Reach for it before reading a large file.

outline("src/auth/session.ts")
imports      1-8
class Session                    12-96
  constructor(client, token)     14-20
  refresh(): Promise<void>       42-58  Renews before expiry.
  revoke(): Promise<void>        60-71

read

Line-numbered, with offset and limit, and capped at 2,000 lines, 2,000 characters a line and 50 KB, so one read cannot flood the context.

read("src/cart/load.ts", { offset: 10, limit: 3 })
h_src/cart/load.ts:10-12:77e0b4d2
  10	import { db } from '../db'
  11
  12	export async function loadCart(req) {

ls

Directory entries with size, kind, modification time, permissions and symlink targets.

ls("src/auth")
session.ts   file  3.1 KB  rw  2m ago
refresh.ts   file  1.2 KB  rw  1h ago
keys         link  → ../../keys

edit

Exact oldText → newText replacements inside a handle’s scope, several in one call as long as they do not overlap.

• Narrow fuzzy matching absorbs smart quotes, dashes and trailing whitespace; a guard rejects matches far larger than the text asked for.
• CRLF line endings and byte-order marks are preserved.

edit({ handle: "h_src/cart/load.ts:10-12:77e0b4d2",
  edits: [{ oldText: "loadCart(req)",
            newText: "loadCart(req, opts)" }] })
✓ 1 replacement · h_src/cart/load.ts:10-12:3c9f11a0

editMatches

One replacement across chosen search hits, all or nothing. Only hits from a search can be swept, so an agent enumerates before it changes anything.

editMatches({ handles: ["s_4e…#1", "s_4e…#3"],
  newText: "loadBasket" })
✓ 2 sites in 2 files

write

Create a file, or overwrite an existing one by its handle.

write({ path: "src/cart/opts.ts", content: "…" })
✓ created · h_src/cart/opts.ts:1-14:d02a6e51

changesNext release

This agent’s own uncommitted hunks, each with the lines it covers now and an edit handle, so an agent can review its work before it says it is done.

• Flags lines another agent has since overwritten.
• Flags lines where this agent built on someone else’s uncommitted work.
• Flags files changed outside Vegvísir: a shell, an IDE, you.

changes()
src/api/checkout.ts   +1 -1  h_…:36:91ab…
src/cart/load.ts      +3 -1  h_…:12-14:3c9f…
! src/cart/load.ts:13 since changed by agent codex-2

commitNext release

A git commit of exactly this agent’s lines. Everything else stays uncommitted in the working tree, even in the same files.

• Real git commit, so hooks, signing and author config apply; core.autocrlf and .gitattributes are respected.
• Refuses with a list of the problems when lines are genuinely tangled.

commit({ message: "Pass an idempotency key to checkout" })
✓ 3f1c9a2 · 2 files · 4 lines
left uncommitted: 3 hunks by claude-1, 1 by you