jany 0.3.0

[!NOTE] Status: experimental. The command definitions and shell integrations may change before 1.0.

$ jany find log files older than 7 days in logs delete
this command is destructive.
$ find logs -type f -iname '*.log' -mtime +7
  logs/old-access.log
  logs/kernel.log
  logs/system.log
  … 2 more

$ find logs -type f -iname '*.log' -mtime +7 -delete█

The last line is not output. It is your next prompt, already filled in. jany prints one shell-quoted line on stdout, and the wrapper from jany --init zsh puts it on the command line. Read it, edit it if you like, press Enter.

$ jany curl psot localhsot 3000 users first_name amanda      # typos, a bare port, key value as two words
$ curl -sS -X POST http://localhost:3000/users -H 'Content-Type: application/json' -H 'Accept: application/json' --data '{"first_name":"amanda"}'

$ jany docker run nginx 8080:80 background named web
$ docker run -d --name web -p 8080:80 nginx

$ jany tar extrct app.tar.gz into dist strip 1                # a definition written by the /jany-register skill
$ tar -xf app.tar.gz --strip-components 1 -C dist

$ jany find empty folders depth 2 count
$ find . -maxdepth 2 -type d -empty | wc -l

jany generalises jind (jev × find) and jurl (jev × curl) into one binary. Each command is a definition directory — three files, no Rust — and adding a command is a job for an LLM skill, not a new crate.

How it works

• rules — the unambiguous shapes are decided by data in schema.toml: paths, globs, 8080:80, KEY=value, +7d, >10M, table words like files/delete/background. If every word resolves, jany never leaves your machine.
• jev — anything left over goes to jev (TypeSafe System One, via OpenRouter) in one request: "what is the role of each word?" plus the extra questions the schema declares (which unit? at least or at most? a typo of which table word?). jev only picks from fixed choices and returns probabilities; it never generates the command.
• repair — fixes what jev cannot see word by word: attach days to 7, let except claim the names after it, pair first_name amanda into key and value.
• assemble.sh — the command's own script (stdin JSON → stdout JSON) turns the role-tagged words into argv. It also says how risky the result is.
• output — the line goes to stdout, everything else to stderr. When the words can't be turned into a command (unresolved, or below a confidence floor), jany exits non-zero and puts jany <command> --hint on the prompt instead, with the reason as a comment. A dangerous result (find -delete) is previewed first with a read-only run. An unsafe one (curl DELETE, docker --privileged) gets a one-line note.

One jev call is 200–700 ms and under $0.0001.

Setup

cargo install jany          # after the crates.io release
# Before the release, install from this checkout:
cargo install --path .
jany --setup                  # store your OpenRouter API key in ~/.config/jany/config.toml (0600)
echo 'eval "$(jany --init zsh)"' >> ~/.zshrc     # bash and fish too; bash is untested
# optional: use `j` as a personal alias for `jany`, with the same completion
printf '%s\n' "alias j='jany'" 'compdef _jany_complete j' >> ~/.zshrc

jany --init does three things: prints the wrapper function, installs the built-in definitions (find, curl, docker run) into ~/.config/jany/cmd/, and installs the /jany-register and /jany-update skills into ~/.agents/skills/ (linked from ~/.claude/skills/ and ~/.codex/skills/ when those exist). It never overwrites a definition that is already there. The skills are in English by default; jany --init zsh --locale ja installs the Japanese one (put the flag in your rc line, since --init rewrites the skill on every shell start).

In zsh the wrapper also shows a dim hint of what you can still say after jany <command> (the definition's [[placeholders]]), e.g. jany find src → <file|dir> <*.log> <older than N days> <delete|count>. It never calls jev. [suggest] enabled = false in ~/.config/jany/config.toml turns it off; JANY_SUGGEST=0 / 1 overrides that for one shell. bash and fish don't have it.

OPENROUTER_API_KEY in the environment takes precedence; a key saved by jind setup or jurl setup is picked up too. Tested on macOS with zsh.

Usage

jany <command> [words ...] [flags] [-- passthrough args]

jany's own actions are flags, so <command> is always the tool's name:

Adding a command

jany --register tar           # optional: scaffold only, without the skill
/jany-register tar            # in Claude Code or Codex: create, fill, and test the definition
jany --test tar

A definition lives in ~/.config/jany/cmd/<name>[/<sub>]/:

The skill reads a reference of every schema key and the two worked examples (find, curl) before writing. The rule of thumb from jind and jurl carries over: cover the 80 % you actually type, pass the rest through after --, and do not trust an assemble.sh that has no cases.

Updating definitions

A new jany can bring new definition features (such as [[placeholders]]) and updated built-ins, but jany --init never touches a definition that is already in place. After upgrading, run:

jany --update                 # built-ins you have not edited are replaced; the rest are listed
/jany-update tar              # in Claude Code or Codex: add what tar lacks, then jany --test tar

jany --update knows a built-in is unedited when every file matches a version jany has shipped (examples/released.txt). An edited built-in is left alone and listed, like your own definitions; /jany-update merges the new parts into it and keeps your edits. jany --update also installs /jany-update itself when it is missing (in the language of the installed /jany-register, or --locale en|ja); skill files already there are left alone.

Config (optional)

~/.config/jany/config.toml

[jev]
model = "typesafe/jev-1.13"
reject_below = 0.5           # below this, no command: exit non-zero and offer `--hint`

[suggest]
enabled = false              # no dim hint in zsh (JANY_SUGGEST=0/1 overrides it)

[cmd.curl.defaults]          # overrides the schema's [defaults]
content_type = "text/plain"

[cmd.find.aliases]
dl = "~/Downloads"

Where it is weak

• The same weaknesses as jind and jurl: a bare word (log, app) can be two roles at once, and jev is often only 0.6–0.9 sure. Write the unambiguous form (*.log) to skip jev.
• Commands whose vocabulary does not close — arbitrary SQL, jq programs, ffmpeg filter graphs — are not a fit. Cover the common forms and pass the rest through.
• Every word, including ones the rules already decided, is sent to jev as context. Roles that may carry secrets (curl headers, docker KEY=value) declare a mask so only a placeholder goes out.