Raw capture — raw/jouzu.md
url: https://www.npmjs.com/package/jouzu date_fetched: 2026-09-08
Agentic AI environment built on the Pi coding agent harness
Latest: 0.1.8 Homepage: https://github.com/shisa-ai/jouzu#readme Repository: {'type': 'git', 'url': 'git+https://github.com/shisa-ai/jouzu.git', 'directory': 'packages/cli'}
Jouzu is Shisa AI's agentic coding harness, built on Pi coding agent.
It comes batteries included with the tools and workflows we use every day:
Jouzu v0.1.x is alpha software. We use it as our daily driver, so it's fully usable, but expect frequent updates and changes.
bash on Linux/macOS; Git Bash on Windows)Windows users should read Windows prerequisites. Signed installers, portable archives, and bundled prerequisites are not part of v0.1.
web_fetch and batch_web_fetch work from the default installation. The rendered-browser tools install their exact Camoufox runtime from npm on the first tff-fetch_url or tff-search_web call, then download the Camoufox browser if needed. These downloads require network access and writable Jouzu state. jz doctor reports whether the optional runtime is absent, ready, or invalid.
On older enterprise Linux distributions, install the GTK/X11/audio libraries required by Firefox. If the system NSS is older than Camoufox requires, set JOUZU_CAMOUFOX_LIBRARY_PATH to a compatible NSS library directory; Jouzu applies it only to the browser child.
npm install -g jouzu
jouzu --version
jz doctor
jz is an exact alias for jouzu. To try the CLI without a global installation:
npx --yes jouzu --version
GitHub Releases include the same tested npm tarball, checksums, and package manifest from v0.1.7 onward. These are npm packages, not standalone executables.
Start Jouzu:
jz
On the first interactive launch, Jouzu asks whether to enable the optional Japanese-support profile. Only an affirmative answer selects ja; declining or pressing Enter selects the provider-neutral core profile. Jouzu saves that choice for later launches. Non-interactive first runs use core and do not manufacture consent.
Before choosing, you can inspect either profile without writing:
jz profile plan --profile core
jz profile plan --profile ja
A normal launch reconciles the selected profile. It stops before launching if a managed target conflicts with a user-owned or modified file.
Inside Jouzu:
/login configures provider authentication in Jouzu's isolated agent root./workflow opens agent definitions and child runs. Configure separate planner, coder, and reviewer models, or add your own roles. See Agents and runs./model or Ctrl+L opens the Jouzu Palette Models view without clearing the prompt draft.Ctrl+P and its reverse binding cycle through available favorites in the current model scope./status reports provider-neutral session, workspace, model, thinking, context, scoped-model, profile, and runtime facts.Ctrl+/ or Ctrl+? opens Jouzu help; /hotkeys lists all Jouzu shortcuts.The Palette shows Models, Workflow, and Settings as top-level sections; Tab and Shift+Tab move between them. The Models view searches exact provider/model identity and display names. ← and → change the Recent, Favorite, or All view; the header reports active results and total selectable inventory. The first launch opens Recent; later launches restore the last view used. Typing or / focuses search; the title shows · Search while search holds focus, and Esc returns to browsing with the query intact before another Esc closes the Palette.
Enter selects the model and stores it as the user-local project default. A new session resolves an explicit --model first, then a resumed session's recorded model, then the project default, then the last dispatched model, then Jouzu's user-wide default and fallback. Restoring a project default or last dispatched model also restores that model's saved thinking (reasoning) level unless you pass --thinking. Explicit resume, continue, session, model, and scoped-model arguments bypass project-default and last-model injection.
Ctrl+F toggles a favorite while browsing and while searching; rebind it through the jouzu.model.toggleFavorite action in keybindings.json. Ctrl+Shift+R refreshes model catalogs and providers without leaving Models, then updates the list; rebind it through the jouzu.model.refresh action. Ctrl+P cycles the favorite list without leaving the current effective model scope. Each model remembers your explicit thinking-level override when you switch back to it. Without an override, Jouzu uses the catalog offering's defaultThinkingLevel, then Pi's configured default. Dispatch history does not override these defaults. Explicit startup thinking arguments, resumed-session levels, and scoped-model thinking pins retain precedence. Changing the thinking level saves the preference immediately, even before another request. Recency changes only after the selected model dispatches its first request, which records its thinking level in global and project recents. Clearing recents keeps explicit thinking preferences. Project defaults, favorites, recents, thinking preferences, the last dispatched model, and the last model view remain in local Jouzu state and contain no prompts, tool results, credentials, or raw project paths.
A direct switch is blocked only when the estimated active context plus a 4,096-token safety margin exceeds the target model's context window. Selecting a context-small model opens a confirmation: press Enter again to compact the full active transcript into a brief and switch after Jouzu rechecks the context, or press Esc to cancel. Bundled pi-vcc handles this compaction under the default profile settings. Jouzu does not infer cache compatibility, model equivalence, cost, routing, privacy, retention, region, or certification guarantees. Those properties belong to the provider and configuration you select unless Jouzu reports verified facts explicitly.
Core and JA load the same release-owned extension set:
schedule_prompt manages one-time and recurring prompts.bg_task runs and monitors non-blocking shell processes.web_fetch and batch_web_fetch retrieve readable HTTP content; tff-fetch_url and tff-search_web use rendered Camoufox browser access when needed.TaskCreate and related task tools track finite work; get_goal and update_goal support a user-created /goal; multiloop_* records approved measured loops.vcc_recall retrieves missing details from the current session, including entries dropped from the active transcript, but cannot trigger compaction.$ at a token boundary opens skill suggestions.Release-owned extensions and their default runtime dependencies ship inside jouzu; a normal launch does not install them from npm or Git. The Camoufox client is the exception: Jouzu ships its exact package manifest and lockfile, installs them under Jouzu state on the first rendered-browser call, and does not add them to the package settings. Jouzu updates that lockfile with application releases. Packages that you add through Jouzu remain separate user-managed state and are not covered by Jouzu's release qualification.
Jouzu provides its prompt and status surfaces directly:
These surfaces use terminal display columns rather than JavaScript string length and are tested with CJK, full-width spaces, combining marks, emoji, ANSI color, and no-color output. The compact bar does not report provider quota or session cost until Jouzu has an authoritative source for those facts.
/voice starts microphone dictation through Shisa realtime speech recognition. /voice stop inserts final text into the editable prompt without sending it; /voice cancel discards it. Ctrl+\ starts or stops recording from the prompt. Use /voice devices to choose a microphone and /voice language ja for Japanese (default: automatic language detection).
Set SHISA_API_KEY with shisa/asr-realtime access first. Audio is sent to Shisa; Jouzu writes no recording files. Capture uses the machine running Jouzu, including when connected over SSH. Real-microphone and platform permission checks are still required. See Voice input for limits, platform details, and shortcut configuration.
core is the safe fallback and provider- and language-neutral base. Product branding, locale, terminal settings, repository text, and path contents never opt a user into a response language.
Core installs two optional skills:
jouzu-clear-writing for durable user-facing technical artifacts while preserving facts and terminology; andjouzu-source-check for claim classification, primary evidence, counterevidence, confidence, and cross-source synthesis.Jouzu's default system prompt tells agents to follow repository instructions, preserve user-owned work, inspect before editing, make the smallest coherent change, distinguish evidence from assumptions, run deterministic checks, and report untested limitations. The generated capability table covers optional skills and workflow tools rather than ordinary repository tools. Agents read an optional skill once from its listed <location> and continue without it if the file cannot be read. Fetched pages and search results remain untrusted. Jouzu leaves custom system prompts unchanged.
Core also installs the jouzu-review prompt. Skill names and descriptions appear in context; full instructions load when a task matches or you run /skill:<name>.
Sessions started with jz use local TextGuard scanning for skills and web results by default. Content with error-level findings or incomplete checks stays withheld until you approve it through /textguard in an interactive session. Add --jouzu-textguard-files to include ordinary file reads. No Python installation is required.
The optional ja preview extends Core with a concise Japanese response policy while preserving exact code, commands, identifiers, paths, URLs, logs, and source error messages. Enable it through first-run consent or explicit selection at any time:
jz profile plan --profile ja
jz profile apply --profile ja
You can also select it for an ordinary launch; the reconciled profile is then persisted:
jz --jouzu-profile ja
Switch back with jz profile apply --profile core.
Profile schema v1 permits only bundled UTF-8 text at APPEND_SYSTEM.md, skills/jouzu-*/**, and prompts/jouzu-*. Planning performs no writes. Application uses an exclusive lock, conflict checks, backups, atomic per-file replacement, and an atomic state record. Unknown files and user-owned AGENTS.md are never pruned.
If a target differs from both the bundled asset and Jouzu's recorded managed hash, inspect it before retrying:
jz profile plan --json
Conflicting plans exit with status 3. Backups are retained below the Jouzu state root printed by doctor.
Default roots are:
| Platform | Agent/config | State and sessions | Cache |
|---|---|---|---|
| Linux | ${XDG_CONFIG_HOME:-~/.config}/jouzu/agent |
${XDG_STATE_HOME:-~/.local/state}/jouzu |
${XDG_CACHE_HOME:-~/.cache}/jouzu |
| macOS | ~/Library/Application Support/Jouzu/agent |
~/Library/Application Support/Jouzu/state |
~/Library/Caches/Jouzu |
| Windows | %APPDATA%\Jouzu\agent |
%LOCALAPPDATA%\Jouzu\state |
%LOCALAPPDATA%\Jouzu\cache |
Override all roots together with --jouzu-home <path> or JOUZU_HOME:
JOUZU_HOME="$PWD/.jouzu" jz doctor
Jouzu does not read normal Pi state during non-interactive commands. On the first interactive setup, it checks an inherited PI_CODING_AGENT_DIR and then ~/.pi/agent. If it finds eligible files, it asks separately before copying custom models.json and saved provider credentials from auth.json. Both prompts default to no. The source files remain unchanged, and Jouzu never replaces an existing destination. Set JOUZU_NO_PI_IMPORT=1 to skip the offer for one launch.
The import rejects symbolic links, non-regular files, oversized files, and files whose top-level JSON value is not an object. It does not import settings.json, keybindings, packages, extensions, skills, prompts, themes, sessions, caches, or trust decisions. Trusted project .pi resources still apply through Pi's project-trust behavior. Pi's documented cross-harness ~/.agents/skills directory is also a shared read surface.
Model catalogs refresh on startup, /reload, and Ctrl+Shift+R in the Models view. Authenticated gateway catalogs at /v1/jouzu/model-catalog supply models through that gateway using the catalog source’s bearer token. Catalog offerings take precedence over matching local models.json entries, including local routes, credentials, headers, and modelOverrides. New gateway providers need no local provider entry. Local-only models keep their configuration; disabling a catalog makes local entries visible again. Saved catalog models keep their source; missing gateway credentials do not cause a switch to a local connection. Other catalogs update metadata on configured providers. These operations do not rewrite models.json.
Jouzu includes a built-in shisa-api source. When the SHISA_API_KEY environment variable holds a bearer token, that source reads the account's model catalog from https://api.shisa.ai/v1/jouzu/model-catalog without any configuration. On interactive startup Jouzu refreshes each enabled source whose credential is available, in the background, while cached catalogs keep serving; sources with a missing credential are not contacted and report no error. The token authenticates catalog and inference requests to the configured gateway origin and is never written to configuration, cache, or diagnostics.
The built-in source can be disabled in Settings / Catalogs. The choice is stored in catalog-overrides.json next to catalogs.json without any credential, and re-enabling restores the built-in defaults. A manually registered source with the same endpoint and env:SHISA_API_KEY credential takes the place of the built-in source, keeping its label, enabled state, and cached catalog. Source id shisa-api is reserved; jouzu catalog status reports a custom entry that claims it with another endpoint.
Open Settings / Catalogs with /catalogs, or use Tab to reach Settings while the Palette is in browse mode. Each custom source stores a label, URL, enabled state, and authentication mode. A opens the add form. Move between fields with ↑ and ↓, change Authentication with ← and →, and press Enter to save. Jouzu accepts an exact URL or a host and finds the catalog endpoint automatically. Plain HTTP URLs are accepted with a warning: HTTP sends the source's bearer token in plain text, so use HTTPS unless the catalog runs on this machine. Esc cancels without writing.
Authentication can be disabled or read as a bearer token from a named environment variable. Jouzu stores only the environment-variable name in catalogs.json; bearer values are sent only in the source's authorization header and never written to configuration, cache, or diagnostics. Without SHISA_API_KEY or a configured catalog source, Jouzu makes no catalog request and uses local model configuration.
Catalog configuration is stored at:
| Platform | Catalog configuration |
|---|---|
| Linux | ${XDG_CONFIG_HOME:-~/.config}/jouzu/catalogs.json |
| macOS | ~/Library/Application Support/Jouzu/catalogs.json |
| Windows | %APPDATA%\Jouzu\catalogs.json |
Settings reports each source's status and model count. Enter edits the selected source; → expands its cached offerings and ← collapses them. A adds, Space enables or disables, R refreshes, and D removes the source registration; removal asks for confirmation. Model changes from these actions apply to the current session immediately. /reload refreshes local provider models and enabled catalogs whose credentials are available before reapplying the active catalog data. The built-in shisa-api row supports only Space; its endpoint and credential reference are managed by Jouzu. Removing a custom source does not remove provider configuration, credentials, favorites, or recents.
Refresh uses ETag/304, validates complete bytes before activation, partitions private cache by source and account, and keeps each source's last valid catalog on network or validation failure. CLI status and refresh operate on all enabled sources or one named source:
jouzu catalog status
jouzu catalog status office
jouzu catalog refresh
jouzu catalog refresh office
JOUZU_MODEL_CATALOG_URL and optional JOUZU_MODEL_CATALOG_TOKEN remain a single-source shorthand when catalogs.json does not exist. Refresh requests never follow redirects, so a bearer token cannot be forwarded to another origin.
A structurally valid large catalog change can be quarantined instead of activated. Review its status, then accept only the exact displayed revision and SHA-256 digest with jouzu catalog accept REVISION --digest SHA256 --source SOURCE_ID.
Catalog producers can validate a file against Jouzu's version 1 structural and semantic contract:
jouzu catalog validate ./catalog.json
jouzu catalog conformance ./remote-catalog.json --json
conformance also requires the remote-stream sequence field. The JSON Schema is installed at dist/catalog/model-catalog-v1.schema.json; runtime validation additionally rejects duplicate JSON keys, broken references, credential-bearing fields, and invalid account scope.
jz doctor
jz doctor --json
jz --version
jz pi --help
jz -- --version
doctor is non-mutating and reports the install/update channel and policy, keybinding-default state, exact Pi tag/commit, platform/runtime prerequisites, resolved roots, profile hashes, package count, authentication presence, proxy/CA status, shared skill surface, warnings, and actionable problems. It reports presence only and does not print credential values.
--json prints the same diagnostics as experimental schema 1, so scripts can read individual fields and issues without parsing the human layout. The report includes "experimental": true; its structure and identifiers may change before the stable machine-diagnostics contract planned for v0.3/v0.4. Exit status is unchanged: 1 when a problem is reported.
Most arguments are forwarded unchanged to Pi. Use pi or -- when a Pi argument collides with a Jouzu command. Pi runtime self-update is blocked because Jouzu owns the exact Pi dependency. Pi package/model operations such as jz update --extensions and jz update --models remain available inside Jouzu state.
On the first interactive launch with no Jouzu keybindings.json, Jouzu seeds two Pi semantic-action defaults in its isolated agent root:
| Key | Pi action | Behavior |
|---|---|---|
Ctrl+Enter |
app.message.followUp |
Queue the editor text as a follow-up while the agent is working |
Ctrl+Up |
app.message.dequeue |
Restore queued messages to the editor |
Tab retains Pi's editor autocomplete and selector behavior. Pi routes application actions without taking an open autocomplete menu's Tab selection. Jouzu does not add raw key checks. On upgrade from v0.1.0, Jouzu replaces an exact Tab follow-up entry only when its ownership receipt proves that Jouzu inserted it, and backs up the file first. User-owned or modified bindings remain unchanged. If another editor action already claims Ctrl+Enter, Jouzu removes its owned Tab entry and reports the conflict.
Inspect and control the defaults explicitly:
jz keybindings status
jz keybindings plan
jz keybindings apply
jz keybindings reset
plan is non-mutating. apply merges only missing Jouzu defaults, backs up the existing file, and refuses differing user values or competing editor actions. reset removes only entries recorded as Jouzu-inserted and leaves a durable opt-out; modified/user-owned entries are preserved as conflicts. JOUZU_NO_KEYBINDING_DEFAULTS=1 disables first-run seeding for one invocation. /hotkeys displays the effective Pi map.
Jouzu also owns a semantic favorite action with code defaults, rebindable through the same keybindings.json:
| Key | Jouzu action | Behavior |
|---|---|---|
Ctrl+F |
jouzu.model.toggleFavorite |
Toggle the selected model's favorite status; also works while the search field holds focus, where it takes precedence over cursor-right |
Ctrl+Shift+R |
jouzu.model.refresh |
Refresh model catalogs and providers, then update the Models list; also works while the search field holds focus |
Ctrl+F encodes as a plain control byte, so it works without an enhanced keyboard protocol. Inside the Models search field it replaces Pi's emacs-style cursor-right; → remains available there. Ctrl+Shift+R needs the Kitty keyboard protocol or modifyOtherKeys; without one it collapses to Ctrl+R, and the Catalogs R refresh remains the unmodified route.
Ctrl+Enter requires modified-Enter reporting through the Kitty keyboard protocol or modifyOtherKeys. Ctrl+Up requires modified-arrow reporting. Windows Terminal supports the Kitty keyboard protocol from version 1.25. In tmux, enable extended-keys with extended-keys-format csi-u; macOS reserves Control+Up for Mission Control.
Ghostty on Linux binds Ctrl+Enter to fullscreen and consumes it before Jouzu receives it. Send it to the application instead:
# ~/.config/ghostty/config
keybind = ctrl+enter=csi:13;5u
jz keybindings plan reports the desired actions and generic modified-key warnings. It does not inspect desktop, terminal, or multiplexer configuration. The key collision map records known defaults and host-verification commands.
An eligible global npm installation checks the configured npm latest channel before the first eligible interactive launch. Each successful check suppresses another registry check for 24 hours; a failed/offline check retries no sooner than one hour later. The default policy is auto-restart: when a newer semantic version exists, Jouzu:
--version behavior;Source checkouts, project-local installs, and ephemeral npx runs are never rewritten automatically; update them through their owning checkout/package invocation. A failed/offline check leaves the current verified installation usable and retries later. Concurrent installs are blocked by a Jouzu state lock. Automatic installation also requires write access to the active global npm prefix; permission failures leave the current installation running and are reported by self-update status and doctor.
Inspect or control the updater explicitly:
jz self-update status
jz self-update check
jz self-update apply
jz self-update policy auto-restart # default
jz self-update policy notify
jz self-update policy off
JOUZU_NO_UPDATE=1 disables startup checks for one invocation. JOUZU_UPDATE_POLICY=auto-restart|notify|off overrides the persisted policy for one process (an invalid value fails safe as off), and JOUZU_UPDATE_INTERVAL_HOURS changes the successful-check cadence. self-update check --json and self-update status --json provide machine-readable results.
Startup checks contact the configured npm registry but send no Jouzu telemetry. A later release may check in the background and offer restart behavior in a TUI modal; v0.1 performs the update before entering Pi so old launcher code never loads newly replaced runtime modules.
Interactive launches clear the current viewport and show a compact adaptive Jouzu header. Set JOUZU_NO_CLEAR=1 to preserve existing terminal output. NO_COLOR disables banner color.
The compatibility suite covers Japanese paths, full-width spaces, hiragana, katakana, half-width kana, kanji, combining marks, emoji, UTF-8 BOM, and CRLF without normalizing or transcoding user files. These data-safety checks do not infer a language preference.
Managed profile assets are UTF-8. Existing CP932/Shift-JIS profile targets produce an unsupported-encoding conflict and remain byte-identical; Jouzu does not guess or convert their encoding.
models.json and auth.json require separate first-run consent; other stock Pi state is not imported.Ctrl+Enter and Ctrl+Up delivery depends on terminal/OS key reporting; both semantic bindings remain user-customizable.From a source checkout, with Bash, Git, npm, and Node.js >=22.19.0 available:
npm run dev:setup # install locked dependencies, check, build, and smoke-test
node packages/cli/dist/cli.js # run this local copy without changing global commands
npm run dev:link # optional: replace global jz/jouzu links with this checkout
The helper installs dependencies with lifecycle scripts disabled and repeats installation when manifests or lockfiles change. Builds record UTC build time, Git commit, and dirty-worktree state. --version displays an identifier such as 0.1.7-dev.20260905-010203+g215b2188; .dirty marks uncommitted files. The offline startup check uses isolated temporary state and a 15-second deadline. No provider key is required.
dev:setup does not change command links or install Git hooks. If global commands already point to this checkout, rebuilding updates the code they run. To opt in to automatic rebuilds after Git operations:
./dev-build.sh install-hooks
./dev-build.sh uninstall-hooks # remove only this helper's hooks
Hooks build without linking, preserve unmanaged hooks, and report build failures without failing Git. They apply only to the checkout that installed them. Set JOUZU_REPO to select another local checkout; the helper never clones or publishes.
The helper and its hermetic npm run test:dev-build suite are tested on Linux; the suite additionally requires Python 3. For Windows without Bash, use npm ci --ignore-scripts, npm run build:dev, and node packages/cli/dist/cli.js; global linking remains an explicit npm link --workspace packages/cli --ignore-scripts step. Native Windows and macOS helper qualification remains separate.
Run npm run release:check for the full release gate. The standard npm run build removes development metadata before packing a release artifact.
See docs/architecture.md for the module map, state-file ownership, update lanes, and bundled profile boundaries. docs/ux.md defines the interaction model for every Jouzu surface, docs/key-collisions.md maps higher-layer shortcut conflicts, and docs/palette-ux.md adds the Palette standards. Pi update review records the candidate checklist, compatibility findings, and reverse-chronological update log.
The opt-in live Japanese tool-flow smoke requires an explicitly selected provider/model and cost budget; it is not part of default tests:
JOUZU_LIVE_SMOKE=1 \
JOUZU_LIVE_PROVIDER="$PROVIDER" \
JOUZU_LIVE_MODEL="$MODEL" \
JOUZU_LIVE_MAX_USD=0.02 \
npm run test:live:ja
It installs the packed artifact in a temporary consumer, permits only read and write, stores no session or transcript, verifies exact Japanese output bytes, and fails if reported cost exceeds the declared budget.
Apache-2.0. See LICENSE.