djinnvim

djinnvim: keyhole editing from the shell

You edit through small viewports, the way a vim user does: search by pattern, look at the echo, edit. Never read a whole file — every command returns the few lines around what it did, and that echo IS your verification (no re-reads needed).

Reach for it when finding or changing something would otherwise mean reading a whole file, when a change repeats across many sites, or when file and shell tools are restricted. Creating a file or rewriting one wholesale is not its job.

Setup — every command, two rules

1. Pin the sandbox root in the same shell command (shell env does not persist between your calls):

   export DJINNVIM_ROOTS=/abs/path/to/project; djinnvim open src/app.py
   

2. Pass each editor command as ONE quoted argument. Single-quote it; switch to double quotes only when the text itself contains a single quote:

   djinnvim edit 'at /old_name/ ciw new_name'
   djinnvim substitute ":%s/'eu-west'/'us-east'/"
   

3. -f PATH names the file to work on, opening it if needed, so edit, substitute, print, matches and write need no separate open call: djinnvim edit -f src/app.py 'at /old/ ciw new'. Without it they use the active buffer. A switch is announced in the echo ([now on ... ]).

State (open buffers, cursor, registers, undo) persists across your shell calls via an auto-spawned per-session daemon — nothing to start or manage. djinnvim status shows it, djinnvim shutdown stops it (unwritten buffers die with it; only write touches disk). Exit codes: 1 = the editor said error: ... (read it — the buffer is untouched), 2 = usage/daemon problem.

The seven verbs

• djinnvim open PATH — open/switch the active buffer and show its head. Optional, given -f above; use it when you want the file's metadata. Relative paths resolve against the root, not your cwd.
• djinnvim motion CMD — move the cursor, one motion per call: /pattern (regex, forward), ?pattern (back), n/N (next/prev — n is ALWAYS forward, N ALWAYS backward, unlike vim), :80 (line), gg/G, fx/Fx (char on the cursor line). Search is strictly after the cursor and wraps, reporting match i of n (wrapped).
• djinnvim matches PATTERN [-C 1] — grep-style listing of every match (capped at 50). Call this before any rename-like edit to see all sites and decoys.
• djinnvim edit CMD — vim normal-mode edit (details below).
• djinnvim substitute CMD — ex command (details below).
• djinnvim print [CMD] — read-only window print (ed/vim :p), the reading tool: 'p' (current line, cursor stays), ':80 p' / ':/def load/ p' (cursor MOVES there, prints it), ':10,25 p' (range; cursor to its last line). Widen with above/below/around
  • tiny (8) / middle (25) / long (50) or a number — ':/def load/ p around middle'; around counts EACH side. Max ~100 lines per call; page by re-addressing a gutter line number.
• djinnvim write — save the active buffer; reports lines changed. write --preview shows the full pending buffer-vs-disk ±diff without writing — the final review before committing.