diff --git a/.gitignore b/.gitignore index f6c0e0f..dd0f21a 100644 --- a/.gitignore +++ b/.gitignore @@ -39,7 +39,13 @@ junie/settings.json !junie/versions !junie/mcp !junie/models +junie/models/*smoca* !junie/skills !junie/commands !junie/agents !junie/vendor + +# ========================= +# Test harness artifacts +# ========================= +tests/baselines/current/ diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..5599359 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,6 @@ +[submodule "junie/vendor/obsidian-plugin-skill"] + path = junie/vendor/obsidian-plugin-skill + url = https://github.com/gapmiss/obsidian-plugin-skill.git +[submodule "junie/vendor/raycast-extension-skill"] + path = junie/vendor/raycast-extension-skill + url = https://github.com/adriangrantdotorg/Raycast-Skill.git diff --git a/.junie/plans/add-starship-prompt.md b/.junie/plans/add-starship-prompt.md new file mode 100644 index 0000000..14cee43 --- /dev/null +++ b/.junie/plans/add-starship-prompt.md @@ -0,0 +1,194 @@ +--- +sessionId: session-260702-225143-1r8n +--- + +# Requirements + +### Overview & Goals + +Add **Starship** as the primary shell prompt, with the current hand-rolled `render_prompt` function kept as a graceful fallback when Starship is not installed. This makes the README accurate (it already claims Starship is used) and gives a richer, more informative prompt out of the box. + +### Scope + +**In Scope:** +- Create a full-featured `starship.toml` in the repo root +- Modify `zshrc` Prompt section: Starship-first, fallback to current `render_prompt` +- Add Starship to macOS Brewfile +- Create a Fedora setup step (`setup/fedora/15-starship.sh`) that installs Starship via the official curl installer +- Symlink `starship.toml` → `~/.config/starship.toml` +- Update README.md to reflect the actual implementation + +**Out of Scope:** +- Removing the existing `render_prompt` function (it stays as fallback) +- Changing any other zshrc sections +- Fedora Atomic Starship setup (separate follow-up if needed) + +# Technical Design + +### Current Implementation + +The Prompt section in `zshrc` (lines 276–287) uses a hardcoded `render_prompt` function assigned to `precmd_functions`: + +```zsh +precmd_functions=(render_prompt) + +function render_prompt { + PROMPT="" + PROMPT+="%(1j.%B%%%b .)" + PROMPT+="%~ " + PROMPT+="%(?.%F{green}.%F{red})%B$%b%f " + RPROMPT="%(?..%F{red}[%?]%f)" +} +``` + +Starship is not referenced anywhere in `zshrc`. No `starship.toml` exists in the repo. Starship is not listed in any package manifest (`Brewfile`, `dnf.txt`, `pacman.txt`, `aur.txt`). The README.md incorrectly claims Starship is used. + +### Key Decisions + +- **Starship-first with fallback**: Use `if command -v starship` guard — when available, `eval "$(starship init zsh)"`; otherwise, keep the existing `render_prompt`. This follows the established zshrc pattern used by FZF, TheFuck, Tailscale, and others. +- **Full-featured `starship.toml`**: Enable most modules with auto-detection so context (git, language versions, etc.) appears only when relevant. This is the user's stated preference. +- **Linux install via curl installer in Fedora setup**: Use the official `https://starship.rs/install.sh` script rather than distro packages. This ensures the latest version and avoids adding Starship to `dnf.txt` / `pacman.txt`. A new Fedora-specific step (`setup/fedora/15-starship.sh`) handles this, following the same pattern as `12-bun.sh` and `13-junie.sh`. +- **macOS install via Homebrew**: Add `brew "starship"` to the Brewfile — consistent with how all other macOS CLI tools are managed. + +### Proposed Changes + +#### 1. New file: `starship.toml` + +Full-featured Starship config at repo root. Key modules: +- `character` — green `$` on success, red `$` on failure (mirrors current behavior) +- `directory` — truncated path with repo root detection +- `jobs` — background job indicator (mirrors current `%(1j...)` ) +- `status` — exit code display on failure (mirrors current RPROMPT) +- `git_branch`, `git_status`, `git_state`, `git_commit` — full git context +- `cmd_duration` — show how long the last command took +- `nodejs`, `python`, `java`, `golang`, `rust`, `bun`, `dotnet` — language versions when detected +- `docker_context` — show active Docker context +- `package` — show project package version +- Plus: `aws`, `gcloud`, `kubernetes`, `terraform`, and other common modules + +#### 2. Modified: `zshrc` (Prompt section, lines 276–287) + +```zsh +########## + +# Prompt + +########## +if command -v starship >/dev/null 2>&1; then + eval "$(starship init zsh)" +else + precmd_functions=(render_prompt) + + function render_prompt { + PROMPT="" + PROMPT+="%(1j.%B%%%b .)" + PROMPT+="%~ " + PROMPT+="%(?.%F{green}.%F{red})%B$%b%f " + RPROMPT="%(?..%F{red}[%?]%f)" + } +fi +``` + +#### 3. Modified: `setup/macos/Brewfile` + +Add `brew "starship"` in alphabetical order (after `sqlite`, before `strace`-equivalent position). + +#### 4. New file: `setup/fedora/15-starship.sh` + +Follows the same pattern as `setup/fedora/12-bun.sh` and `setup/fedora/13-junie.sh` — sources `setup/general/common.bash`, implements `presteps()` (require curl), `help()`, and `run()`. Runs `curl -sS https://starship.rs/install.sh | sh -s -- -y` to install Starship to `~/.local/bin`. Idempotent: checks for existing `starship` binary before installing. This step only runs on Fedora (regular), not on macOS or Fedora Atomic. + +#### 5. Modified: `setup/general/01-symlinks.sh` + +Add: `ensure_symlink "$REPO_DIR/starship.toml" "$HOME/.config/starship.toml"` + +#### 6. Modified: `README.md` + +- Prompt section: describe Starship-first with fallback +- Repository Layout table: update zshrc description +- Remove "Write a `starship.toml`" recommendation + +### Data Models / Contracts + +**`starship.toml`** — standard Starship configuration (TOML format). See https://starship.rs/config/ for the full schema. + +**Setup step contract** (`setup/fedora/15-starship.sh`): +```bash +presteps() { require_command curl; } +help() { echo "Install Starship prompt via official installer"; } +run() { /* check for existing binary, run curl installer */ } +``` + +### File Structure + +``` +config/ +├── starship.toml # NEW — Starship configuration +├── zshrc # MODIFIED — Prompt section (lines 276–287) +├── README.md # MODIFIED — Prompt description + recommendations +└── setup/ + ├── general/ + │ └── 01-symlinks.sh # MODIFIED — add starship.toml symlink + ├── fedora/ + │ └── 15-starship.sh # NEW — curl installer step (Fedora only) + └── macos/ + └── Brewfile # MODIFIED — add brew "starship" +``` + +### Architecture Diagram + +```mermaid +graph TD + A[zshrc sourced] --> B{starship binary exists?} + B -->|Yes| C[starship init zsh] + B -->|No| D[render_prompt fallback] + + E[setup.sh] --> F[general/01-symlinks.sh] + E --> G[fedora/15-starship.sh] + E --> H[macos/02-brew-bundle.sh] + + F --> I[~/.config/starship.toml symlink] + G -->|Fedora only| J[curl installer → ~/.local/bin/starship] + H -->|macOS only| K[brew install starship] + + I --> C + J --> C + K --> C +``` + +### Risks + +- **`~/.local/bin` not in PATH on Linux**: The curl installer places Starship in `~/.local/bin`. The zshrc already adds `$HOME/.local/bin` to PATH (line 322, for Junie), so this is covered. +- **Starship init overhead**: `starship init zsh` adds a small overhead to shell startup. This is inherent to Starship and acceptable given the feature gain. The fallback path has zero overhead. +- **Symlink order**: The `starship.toml` symlink must exist before Starship runs. Since `01-symlinks.sh` runs before any tool installation steps, and Starship gracefully handles a missing config file (uses defaults), this is not a real issue. + +# Delivery Steps + +### ✓ Step 1: Create starship.toml with full-featured configuration +Create a full-featured Starship configuration file at the repo root. + +- Create `starship.toml` with modules enabled: directory, character (green/red $), jobs, status (exit code), git_branch, git_status, git_commit, git_state, cmd_duration, nodejs, python, java, golang, rust, docker_context, bun, package, and more. +- Mirror the current prompt's key behaviors: green `$` on success / red `$` on failure, job count indicator, exit code display. +- Use Starship's auto-detection so modules only appear when relevant (e.g., Node.js version only shows in Node projects). + +### ✓ Step 2: Modify zshrc prompt section for Starship with fallback +Replace the hardcoded `render_prompt` with Starship-first logic that falls back to the current custom prompt. + +- In the Prompt section (lines 276–287), wrap the existing `render_prompt` function in an `else` branch. +- Add an `if command -v starship` guard that runs `eval "$(starship init zsh)"` when Starship is available. +- Keep the existing `render_prompt` function intact as the fallback for when Starship is not installed. +- Follow the existing zshrc pattern for optional tools (e.g., FZF at lines 308–310, TheFuck at lines 407–409). + +### ✓ Step 3: Update package manifests and setup scripts for Starship installation +Add Starship to all platform package manifests and setup infrastructure. + +- Add `brew "starship"` to `setup/macos/Brewfile` (macOS install). +- Create `setup/fedora/15-starship.sh` — a Fedora-specific setup step that installs Starship via the official curl installer (`curl -sS https://starship.rs/install.sh | sh -s -- -y`). Follows the same pattern as `setup/fedora/12-bun.sh` and `setup/fedora/13-junie.sh`: sources `setup/general/common.bash`, implements `presteps()` (require curl), `help()`, and `run()` with idempotency check. +- Add `ensure_symlink "$REPO_DIR/starship.toml" "$HOME/.config/starship.toml"` to `setup/general/01-symlinks.sh` so the config is symlinked into place. + +### ✓ Step 4: Update README.md to reflect Starship integration +Sync the README.md with the actual implementation. + +- Update the Prompt section (lines 376–378) to describe the Starship-first approach with fallback to the custom prompt. +- Update the zshrc description in the Repository Layout table (line 73) to reflect the current state. +- Remove the "Write a `starship.toml`" recommendation (line 727) since it will now exist. +- Ensure the TODO checkboxes (lines 738, 753, 767, 781) remain accurate. \ No newline at end of file diff --git a/.junie/plans/refactor-setup-step-architecture.md b/.junie/plans/refactor-setup-step-architecture.md new file mode 100644 index 0000000..41f88f5 --- /dev/null +++ b/.junie/plans/refactor-setup-step-architecture.md @@ -0,0 +1,483 @@ +--- +sessionId: session-260702-155421-1v2a +--- + +# Requirements + +### Overview & Goals +Refactor the repo’s OS setup system into a numbered step-script architecture, with a Podman + Makefile + bats-core harness established **before** migration. The migration must preserve current macOS, Fedora, Fedora Atomic, and Manjaro setup behavior while making the setup process discoverable, selectively runnable, and idempotent. + +### In Scope +- Replace the current monolithic/platform-script model with: + - Root `setup.sh` as the only entry point. + - New `setup/` directory containing exactly the platform step directories requested: `general/`, `macos/`, `manjaro/`, `fedora/`, `fedora-atomic/`. + - Numbered executable step scripts such as `01-base.sh`, `02-zsh.sh`, run in lexical order. +- Execute `general/` steps first, then the detected OS-specific directory. +- Implement CLI selection modes: + - default/all: run all discovered applicable steps. + - include-only: run exactly selected step IDs/names after discovery and ordering. + - exclude: run all discovered applicable steps except selected step IDs/names. + - `--interactive`: show an `fzf --multi` checklist when `fzf` is available; otherwise print a clear fallback message and require/accept flag-based selection. +- Enforce a step contract where every step script dispatches on `$1` to `presteps`, `help`, and `run`. +- Share as much setup behavior as possible through `setup/general/`, while keeping platform-dependent work out of it: + - Runnable `general/` steps cover only truly OS-agnostic work. + - Non-executable helpers in `setup/general/common.bash` provide only platform-neutral primitives such as logging, manifest parsing, symlink handling, directory creation, text-file edits, and guarded Git clones. + - Flatpak, package-manager logic, installer/downloader workflows, GUI app installers, and OS-specific service/shell behavior stay in the relevant OS directory. +- Split the current large per-OS scripts into small, focused numbered steps rather than broad “do everything for this OS” scripts. +- Treat idempotency as a hard requirement: repeated full runs and repeated selected-step runs must be safe and should no-op when the desired state already exists. +- Add a Podman-driven `Makefile` test matrix with bats-core tests: + - `make test-fedora` + - `make test-manjaro` + - `make test-fedora-atomic` + - `make test-macos` + - optional aggregate `make test` +- Establish the harness against the **current** scripts first, run it, and record baseline pass/fail/skip results before migration. +- Re-run the same tests after migration and compare against baseline. + +### Out of Scope +- No implementation in this planning step. +- No conversion to a different shell language; continue using Bash-style scripts. +- No CI provider setup unless added later as a separate task. +- No guaranteed real macOS execution inside Podman; `test-macos` uses a mocked Darwin/Homebrew environment as required. + +### User Choices Applied +- **Test harness strategy:** favor real package-manager execution inside disposable containers wherever practical; macOS remains mocked, and Fedora Atomic may fall back to a documented `rpm-ostree` mock if no practical rpm-ostree-capable image works. +- **Step selection semantics:** include-only means **exactly the selected discovered steps** run; `general/` steps are not implicitly added unless selected. +- **Baseline strictness:** record baseline pass/fail/skip artifacts without blocking migration on known current-script limitations. +- **Latest refinement:** maximize truly OS-agnostic shared logic in `setup/general/`, keep Flatpak and installer/downloader logic OS-specific, make every step idempotent, and split current setup files into smaller chunks. + +# Technical Design + +### Current Implementation +- `setup.sh` currently mixes base setup and dispatch: + - Defines `link_path()` and `setup_symlinks()` for dotfile symlinks. + - Links `zshrc`, `vimrc`, `gitconfig`, `vim/`, `nvim/`, `lazygit/`, `junie/`, `ghostty/`, `Nextcloud/`, and selected `ssh/` files. + - Calls `setup.git-filters.sh` from `setup_symlinks()`. + - Detects OS using `uname -s`, `/etc/fedora-release`, `/etc/manjaro-release`, and `rpm-ostree` availability. + - Dispatches to `setup.macos.sh`, `setup.fedora.sh`, `setup.atomic-fedora.sh`, or `setup.manjaro.sh`. +- `setup.macos.sh` handles Homebrew installation, `packages/macos/Brewfile`, SSH agent/keychain setup, and the Dracula Vim theme. +- `setup.fedora.sh` handles `dnf`, COPR, Flatpak, ZSH plugins, tealdeer/Vim directories, JetBrains Toolbox, Proton Bridge, Bun, Junie, and Tailscale. +- `setup.atomic-fedora.sh` handles `rpm-ostree`, Flatpak, toolbox creation/package installation, and toolbox extras for `latex`, `mobile`, and `cli-dev`. +- `setup.manjaro.sh` handles `pacman`, AUR via `yay`, ZSH plugins, shell/default services, CUPS/firewall/clamav, and scripts under `packages/manjaro/external/`. +- Repeated behavior should be shared only where platform-neutral. `setup/general/common.bash` should cover manifest parsing, directory creation, symlink checks, guarded Git clones, and other shell primitives; Flatpak guards, default-shell changes, package-manager operations, JetBrains Toolbox installation, version-manager installers, and downloaded archive/executable workflows should be implemented in OS-specific steps or OS-specific helper companions. +- `packages/` currently stores manifests and executable Manjaro external scripts: + - `packages/macos/Brewfile` plus tracked `Brewfile.old*` backups. + - `packages/fedora/{dnf.txt,flatpak.txt,copr.txt}`. + - `packages/fedora-atomic/{rpm-ostree.txt,flatpak.txt,toolboxes.txt,toolboxes/*.txt}`. + - `packages/manjaro/{pacman.txt,aur.txt,external/*.sh}`. +- `README.md` documents the current setup layout and must be updated after migration. + +### Target Runner Behavior +Root `setup.sh` becomes orchestration-only: +1. Resolve `REPO_DIR`. +2. Detect platform: + - `Darwin` → `macos`. + - Linux + `/etc/fedora-release` + `rpm-ostree` → `fedora-atomic`. + - Linux + `/etc/fedora-release` without `rpm-ostree` → `fedora`. + - Linux + `/etc/manjaro-release` → `manjaro`. +3. Discover executable `*.sh` steps in: + - `setup/general/` + - `setup/$OS_ID/` +4. Build an ordered step list: all `general/` scripts first, then all OS-specific scripts, each sorted lexically by filename. +5. Apply selection filters: + - default/`--all`: keep all discovered steps. + - include-only: keep exactly selected step IDs/names. + - exclude: drop selected step IDs/names. + - `--interactive`: if `fzf` exists, list discovered steps with help text and run selected entries; if absent, exit with a clear message showing equivalent flag usage. +6. For each selected step, run: + - `./step.sh presteps` + - `./step.sh run` +7. Run steps as separate processes, never by sourcing them. +8. Print a summary of executed, skipped, and failed steps. + +### Step Identity and Selection +Each discovered step has stable selectors: +- Fully qualified ID: `/`, e.g. `general/01-symlinks.sh`. +- Filename shorthand when unambiguous, e.g. `01-symlinks.sh`. +- Basename without extension when unambiguous, e.g. `01-symlinks`. + +Explicit include-only examples: +```bash +./setup.sh --only general/01-symlinks.sh +./setup.sh --only fedora/06-flatpak-apps.sh,fedora/08-zsh-plugins.sh +./setup.sh --interactive +``` + +### Exact Step Interface Template +Every step script should use this template shape. Steps may source `setup/general/common.bash` for platform-neutral primitives; OS-specific steps may also source a non-executable `setup//common.bash` for platform-dependent helpers such as Flatpak, package-manager, downloader, or installer guards. Helper files are not executable and are not discovered as steps. +```bash +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash + +source "$REPO_DIR/setup/general/common.bash" + +if [[ "$SCRIPT_DIR" != "$REPO_DIR/setup/general" && -f "$SCRIPT_DIR/common.bash" ]]; then + # shellcheck source=common.bash + source "$SCRIPT_DIR/common.bash" +fi + +presteps() { + # Required preconditions only; fail fast with actionable messages. + # Example: require_command git + return 0 +} + +help() { + cat <<'EOF' +Short description of what this step configures and what state it ensures. +EOF +} + +run() { + # Idempotent setup logic. Check current state before every mutation. + return 0 +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac +``` + +### Shared General Strategy +`setup/general/` is the shared-code location for platform-neutral behavior only. It contains runnable general steps and a non-executable `common.bash` helper library: +- `setup/general/common.bash` — shared primitive helpers such as `log`, `die`, `require_command`, `read_manifest`, `ensure_dir`, `ensure_symlink`, `ensure_git_config`, `ensure_git_clone`, `ensure_line_present`, and `command_exists`. +- Runnable `general/*.sh` steps are limited to OS-agnostic work that can safely run before OS-specific package installation. +- `setup/general/common.bash` must not contain Flatpak helpers, package-manager wrappers, GUI app installers, network downloader/installers, `brew`/`dnf`/`pacman`/`rpm-ostree`/`yay` logic, or OS service/shell mutation logic. +- OS-specific directories may include their own non-executable `common.bash` companion for platform-dependent helpers used by multiple steps in that OS directory. +- If a workflow can share only primitive mechanics, keep those primitives in `setup/general/common.bash` and keep the executable step plus platform-specific helper code in the relevant OS directory. + +### Idempotency Rules +Every `run()` must prove or query current state before making changes: +- Symlinks are changed only when the target differs; backups are created once with deterministic names or skipped when already backed up. +- Package steps use OS-specific package-manager no-op features or pre-query installed state (`dnf`, `rpm-ostree`, `pacman`, `yay`, `brew`, `flatpak`) before installing. +- Flatpak, Homebrew, rpm-ostree, dnf, pacman/yay, and service checks live in the relevant OS directory, not in `setup/general/common.bash`. +- Git clone steps check for an existing checkout and optionally fast-forward/update only when safe. +- Download/install steps live in the relevant OS directory and check the final executable, app, directory, or version before downloading; temporary archives are cleaned. +- Service steps check availability and current enabled/running/operator state before calling `systemctl`, `tailscale`, or similar commands. +- `presteps()` validates prerequisites but does not mutate state; `help()` only prints. + +### Proposed Step Mapping +`general/`: +- `setup/general/common.bash` — non-executable platform-neutral helper library for all steps. +- `setup/general/01-symlinks.sh` — move `setup.sh` symlink/linking logic here, including `$HOME/.config`, `$HOME/.ssh`, and idempotent backup/link behavior. +- `setup/general/02-git-filters.sh` — move or replace `setup.git-filters.sh`; register `pkcs11-provider` and `scrub-apikey` filters idempotently. +- `setup/general/03-vim-base.sh` — create shared Vim directories such as `$HOME/.vim/undo` and other OS-agnostic editor directories only; any theme download/install remains OS-specific. + +`macos/`: +- `setup/macos/common.bash` — non-executable macOS helper library for Homebrew, keychain, and macOS-specific downloader/installer guards. +- `setup/macos/01-homebrew.sh` — current `ensure_homebrew()` behavior, guarded by `command -v brew`. +- `setup/macos/02-brew-bundle.sh` — move `packages/macos/Brewfile` to `setup/macos/Brewfile` and run `brew bundle --file` only after Homebrew is available. +- `setup/macos/03-ssh-agent.sh` — current SSH agent startup checks from `ensure_ssh_agent()`. +- `setup/macos/04-ssh-keychain.sh` — current `add_ssh_keys_to_keychain()` behavior, guarded so already-added keys are not repeatedly added. +- `setup/macos/05-vim-theme.sh` — current macOS Vim theme install logic, made idempotent and kept out of `general/` because it downloads/installs platform-specific assets. + +`fedora/`: +- `setup/fedora/common.bash` — non-executable Fedora helper library for `dnf`, COPR, Flatpak, service, and Fedora-specific downloader/installer guards. +- `setup/fedora/01-system-update.sh` — `sudo dnf -y upgrade --refresh`. +- `setup/fedora/02-copr-repos.sh` — COPR enablement from `copr.txt`, checking enabled repos before calling `dnf copr enable`. +- `setup/fedora/03-dnf-packages.sh` — move `packages/fedora/dnf.txt` to `setup/fedora/dnf.txt`; install missing packages with `sudo dnf install -y`. +- `setup/fedora/04-copr-packages.sh` — install the hardcoded COPR-dependent packages currently in `setup.fedora.sh` (`lazygit`, `scrcpy`, `codium`, `steam`, `proton-vpn-gnome-desktop`) or move them to a focused companion manifest. +- `setup/fedora/05-flatpak-runtime.sh` — install/verify Flatpak and ensure Flathub exists. +- `setup/fedora/06-flatpak-apps.sh` — move `packages/fedora/flatpak.txt` to `setup/fedora/flatpak.txt`; install only missing Flatpak apps. +- `setup/fedora/07-default-shell.sh` — perform Fedora-specific default-shell checks after packages are installed. +- `setup/fedora/08-zsh-plugins.sh` — install/update ZSH plugins using platform-neutral Git clone primitives plus Fedora-specific prerequisites. +- `setup/fedora/09-tealdeer.sh` — create `$HOME/.config/tealdeer` and run `tldr --update` only when `tldr` is present. +- `setup/fedora/10-jetbrains-toolbox.sh` — use Fedora-specific guarded downloader/installer logic and avoid launching repeatedly on every run. +- `setup/fedora/11-proton-bridge.sh` — install Proton Bridge only when the package/app is absent, using Fedora-specific package/download checks. +- `setup/fedora/12-bun.sh` — use Fedora-specific guarded installer logic only when `bun` is absent. +- `setup/fedora/13-junie.sh` — use Fedora-specific guarded installer logic only when Junie is absent. +- `setup/fedora/14-tailscale.sh` — enable/start Tailscale and set operator only when needed and supported. + +`fedora-atomic/`: +- `setup/fedora-atomic/common.bash` — non-executable Fedora Atomic helper library for `rpm-ostree`, Flatpak, toolbox, and Atomic-specific downloader/installer guards. +- `setup/fedora-atomic/01-system-upgrade.sh` — `sudo rpm-ostree upgrade`. +- `setup/fedora-atomic/02-host-packages.sh` — move `rpm-ostree.txt`; layer only missing host packages where detectable. +- `setup/fedora-atomic/03-default-shell.sh` — perform Fedora Atomic-specific default-shell checks after layered package checks. +- `setup/fedora-atomic/04-zsh-plugins.sh` — install/update ZSH plugins using platform-neutral Git clone primitives plus Atomic-specific prerequisites. +- `setup/fedora-atomic/05-tealdeer.sh` — create tealdeer/Vim support directories and update `tldr` when available. +- `setup/fedora-atomic/06-flatpak-remote.sh` — ensure Flathub exists. +- `setup/fedora-atomic/07-flatpak-apps.sh` — move `flatpak.txt`; install only missing apps. +- `setup/fedora-atomic/08-toolbox-create.sh` — move `toolboxes.txt`; create only missing toolboxes. +- `setup/fedora-atomic/09-toolbox-packages.sh` — move `toolboxes/*.txt`; install per-toolbox packages with guarded `toolbox run` calls. +- `setup/fedora-atomic/10-toolbox-latex.sh` — LTEX LS extras, guarded by final binary/path checks. +- `setup/fedora-atomic/11-toolbox-mobile.sh` — `ktlint` and `swiftlint` extras, guarded by executable/version checks. +- `setup/fedora-atomic/12-toolbox-cli-dev.sh` — Jabba/Pyenv/NVM extras, using Fedora Atomic/toolbox-specific guarded installer checks. +- `setup/fedora-atomic/99-reboot-notice.sh` — print rpm-ostree reboot notice only when layering requested/changed if detectable. + +`manjaro/`: +- `setup/manjaro/common.bash` — non-executable Manjaro helper library for `pacman`, `yay`, services, AUR, and Manjaro-specific downloader/installer guards. +- `setup/manjaro/01-system-update.sh` — `sudo pacman -Syu --noconfirm` with container-aware handling. +- `setup/manjaro/02-pacman-packages.sh` — move `pacman.txt`; install missing packages with `pacman -S --needed`. +- `setup/manjaro/03-yay-bootstrap.sh` — ensure `yay` exists before AUR package installation. +- `setup/manjaro/04-aur-packages.sh` — move `aur.txt`; install missing AUR packages with `yay -S --needed`. +- `setup/manjaro/05-default-shell.sh` — perform Manjaro-specific default-shell checks after packages are installed. +- `setup/manjaro/06-zsh-plugins.sh` — install/update ZSH plugins using platform-neutral Git clone primitives plus Manjaro-specific prerequisites. +- `setup/manjaro/07-printing.sh` — CUPS package/service setup with current-state checks. +- `setup/manjaro/08-firewall.sh` — nftables/ufw setup with current-state checks. +- `setup/manjaro/09-clamav.sh` — ClamAV service/update setup with current-state checks. +- `setup/manjaro/10-jetbrains-toolbox.sh` — port `external/10-jetbrains-toolbox.sh` using Manjaro-specific guarded downloader/installer logic. +- `setup/manjaro/11-jabba.sh` — port `external/20-jabba.sh` using Manjaro-specific guarded installer checks. +- `setup/manjaro/12-joplin.sh` — port `external/30-joplin.sh` with final app/executable checks. +- `setup/manjaro/13-cisco-note.sh` — port `external/40-cisco-note.sh` as an idempotent note/artifact step. +- `setup/manjaro/14-celeste-note.sh` — port `external/50-celeste-note.sh` as an idempotent note/artifact step. + +### Concrete File List +Create: +- `Makefile` +- `tests/README.md` +- `tests/containers/Containerfile.fedora` +- `tests/containers/Containerfile.manjaro` +- `tests/containers/Containerfile.fedora-atomic` +- `tests/containers/Containerfile.macos-mock` +- `tests/bats/helpers/common.bash` +- `tests/bats/helpers/assertions.bash` +- `tests/bats/smoke.bats` +- `tests/bats/idempotency.bats` +- `tests/bats/assertions-fedora.bats` +- `tests/bats/assertions-manjaro.bats` +- `tests/bats/assertions-fedora-atomic.bats` +- `tests/bats/assertions-macos.bats` +- `tests/baselines/README.md` +- `setup/general/common.bash` +- `setup/general/01-symlinks.sh` +- `setup/general/02-git-filters.sh` +- `setup/general/03-vim-base.sh` +- `setup/macos/common.bash` +- `setup/macos/01-homebrew.sh` +- `setup/macos/02-brew-bundle.sh` +- `setup/macos/03-ssh-agent.sh` +- `setup/macos/04-ssh-keychain.sh` +- `setup/macos/05-vim-theme.sh` +- `setup/fedora/common.bash` +- `setup/fedora/01-system-update.sh` +- `setup/fedora/02-copr-repos.sh` +- `setup/fedora/03-dnf-packages.sh` +- `setup/fedora/04-copr-packages.sh` +- `setup/fedora/05-flatpak-runtime.sh` +- `setup/fedora/06-flatpak-apps.sh` +- `setup/fedora/07-default-shell.sh` +- `setup/fedora/08-zsh-plugins.sh` +- `setup/fedora/09-tealdeer.sh` +- `setup/fedora/10-jetbrains-toolbox.sh` +- `setup/fedora/11-proton-bridge.sh` +- `setup/fedora/12-bun.sh` +- `setup/fedora/13-junie.sh` +- `setup/fedora/14-tailscale.sh` +- `setup/fedora-atomic/common.bash` +- `setup/fedora-atomic/01-system-upgrade.sh` +- `setup/fedora-atomic/02-host-packages.sh` +- `setup/fedora-atomic/03-default-shell.sh` +- `setup/fedora-atomic/04-zsh-plugins.sh` +- `setup/fedora-atomic/05-tealdeer.sh` +- `setup/fedora-atomic/06-flatpak-remote.sh` +- `setup/fedora-atomic/07-flatpak-apps.sh` +- `setup/fedora-atomic/08-toolbox-create.sh` +- `setup/fedora-atomic/09-toolbox-packages.sh` +- `setup/fedora-atomic/10-toolbox-latex.sh` +- `setup/fedora-atomic/11-toolbox-mobile.sh` +- `setup/fedora-atomic/12-toolbox-cli-dev.sh` +- `setup/fedora-atomic/99-reboot-notice.sh` +- `setup/manjaro/common.bash` +- `setup/manjaro/01-system-update.sh` +- `setup/manjaro/02-pacman-packages.sh` +- `setup/manjaro/03-yay-bootstrap.sh` +- `setup/manjaro/04-aur-packages.sh` +- `setup/manjaro/05-default-shell.sh` +- `setup/manjaro/06-zsh-plugins.sh` +- `setup/manjaro/07-printing.sh` +- `setup/manjaro/08-firewall.sh` +- `setup/manjaro/09-clamav.sh` +- `setup/manjaro/10-jetbrains-toolbox.sh` +- `setup/manjaro/11-jabba.sh` +- `setup/manjaro/12-joplin.sh` +- `setup/manjaro/13-cisco-note.sh` +- `setup/manjaro/14-celeste-note.sh` + +Move: +- `packages/macos/Brewfile` → `setup/macos/Brewfile` +- `packages/fedora/dnf.txt` → `setup/fedora/dnf.txt` +- `packages/fedora/flatpak.txt` → `setup/fedora/flatpak.txt` +- `packages/fedora/copr.txt` → `setup/fedora/copr.txt` +- `packages/fedora-atomic/rpm-ostree.txt` → `setup/fedora-atomic/rpm-ostree.txt` +- `packages/fedora-atomic/flatpak.txt` → `setup/fedora-atomic/flatpak.txt` +- `packages/fedora-atomic/toolboxes.txt` → `setup/fedora-atomic/toolboxes.txt` +- `packages/fedora-atomic/toolboxes/*.txt` → `setup/fedora-atomic/toolboxes/*.txt` +- `packages/manjaro/pacman.txt` → `setup/manjaro/pacman.txt` +- `packages/manjaro/aur.txt` → `setup/manjaro/aur.txt` +- `packages/manjaro/external/10-jetbrains-toolbox.sh` → `setup/manjaro/10-jetbrains-toolbox.sh` +- `packages/manjaro/external/20-jabba.sh` → `setup/manjaro/11-jabba.sh` +- `packages/manjaro/external/30-joplin.sh` → `setup/manjaro/12-joplin.sh` +- `packages/manjaro/external/40-cisco-note.sh` → `setup/manjaro/13-cisco-note.sh` +- `packages/manjaro/external/50-celeste-note.sh` → `setup/manjaro/14-celeste-note.sh` + +Modify: +- `setup.sh` — rewrite into the runner/dispatcher only. +- `README.md` — update quick start, layout, setup system docs, package manifest paths, and test harness docs. +- `.gitignore` — add test/baseline artifact ignores only if generated logs are not meant to be tracked. + +Delete after migration: +- `setup.macos.sh` +- `setup.fedora.sh` +- `setup.atomic-fedora.sh` +- `setup.manjaro.sh` +- `setup.git-filters.sh` after its behavior is represented by `setup/general/02-git-filters.sh`. +- `packages/` after all manifests and companion scripts are moved. +- `packages/macos/Brewfile.old`, `Brewfile.old.20260331072104`, and `Brewfile.old.20260615082215` unless intentionally preserved as companion historical files. + +### Architecture Diagram +```mermaid +graph TD + U[User / Makefile] --> R[setup.sh runner] + R --> D[OS detection] + R --> G[discover setup/general/*.sh] + R --> O[discover setup//*.sh] + H[general common] --> P + H --> S + OH[os common] --> S + G --> F[selection filters] + O --> F + F --> P[step presteps process] + P --> S[step run process] + S --> M[manifests / companion files] + + T[Podman + bats] --> U + T --> B[baseline artifacts] + T --> C[post-migration comparison] +``` + +### Key Risks and Mitigations +- **macOS testability limits:** Podman cannot run real macOS. `test-macos` will use a Linux container with mocked `uname`, `brew`, `ssh-agent`, and `ssh-add` behavior; the plan should clearly label this as contract/path validation, not full macOS validation. +- **Fedora Atomic in containers:** Real `rpm-ostree` may not function in ordinary containers. Start with an rpm-ostree-capable image; if impractical, use a documented fallback mock for `rpm-ostree` while keeping real Flatpak/toolbox tests where possible. +- **Real package installs are slow/flaky:** The user selected real installs. Keep containers disposable, allow per-OS targets, and record baseline results so network/repository failures are visible rather than hidden. +- **Idempotency gaps:** Current `install_toolbox()` launches Toolbox every run, Proton/Bun/Junie installers may rerun, and some downloads are not guarded. Migration must add explicit checks before download/install/launch; a step is incomplete until its second run is a safe no-op or an explicitly documented package-manager no-op. +- **General-first ordering:** Some workflows, such as ZSH plugin setup or default shell changes, depend on packages installed by OS-specific steps. Keep only platform-neutral primitives in `setup/general/common.bash`; schedule the executable step and any Flatpak/package-manager/installer/downloader helper code in the OS-specific directory when it must run after OS package installation. +- **`chsh` and system services in containers:** `chsh`, `systemctl enable --now`, Tailscale, CUPS, firewall, and ClamAV may be limited in containers; tests should assert graceful behavior or mark known baseline limitations. +- **Tracked historical Brewfiles:** Existing `Brewfile.old*` files need a deliberate delete-or-preserve decision during migration. +- **Platform-dependent over-sharing:** Flatpak, installer/downloader, package-manager, and service helpers are easy to over-generalize but differ by OS. Keep them in `setup//common.bash` or the individual OS step, even if this causes some duplication. +- **Runner complexity:** Keep `setup.sh` orchestration-only and avoid embedding package setup logic back into the runner. + +# Testing + +### Validation Approach +The test harness is built before migration and run against the current scripts. Results are recorded as baseline artifacts, then the same test targets are run after migration and compared. Since the selected strategy favors real installs, Linux containers should run actual package managers where practical; macOS remains mocked and Fedora Atomic has a documented fallback if real `rpm-ostree` is not viable. + +### Makefile Matrix +- `make test-fedora` — build/run Fedora container and execute bats. +- `make test-manjaro` — build/run Manjaro container and execute bats. +- `make test-fedora-atomic` — build/run Atomic-capable container or fallback mock container and execute bats. +- `make test-macos` — build/run mocked macOS environment and execute bats. +- `make test` — run the full matrix. +- `make baseline` — run current-script matrix and store results under `tests/baselines/`. +- `make compare-baseline` — compare post-migration bats summaries/logs with recorded baseline. + +### Bats Layers +1. **Smoke** + - Current phase: invoke existing `setup.sh` under each OS/container target. + - Migrated phase: invoke new `setup.sh` runner for each OS/container target. + - Assert the command exits successfully or records expected known skips. +2. **Idempotency** + - Run setup twice in the same container/home directory. + - Assert the second run exits cleanly and reports already-satisfied state wherever possible. + - Assert no duplicate symlink backups, repeated clone directories, repeated Flatpak remotes, repeated toolbox creation failures, repeated downloads, repeated GUI launches, or repeated package requests where installed-state queries are practical. +3. **Assertions** + - Assert expected files, symlinks, directories, package-manager state, and service configuration outcomes. + +### Per-OS Test Cases +Fedora: +- Smoke: current `setup.sh` detects Fedora and dispatches to `setup.fedora.sh`; migrated runner detects `fedora` and discovers `general/` + `fedora/` steps. +- Idempotency: second run of symlinks, COPR enabling, `dnf install`, Flatpak remote/app setup, default shell, ZSH plugin clone checks, tealdeer/Vim setup, JetBrains Toolbox, Proton Bridge, Bun/Junie guards, and Tailscale service step is safe. +- Assertions: `~/.zshrc`, `~/.vimrc`, `~/.gitconfig`, `~/.config/nvim`, `~/.config/lazygit`, `~/.ssh/config`; `dnf` packages from `setup/fedora/dnf.txt`; COPRs from `setup/fedora/copr.txt`; Flatpaks from `setup/fedora/flatpak.txt`; `~/.zsh/zsh-autosuggestions`, `~/.zsh/zsh-syntax-highlighting`, `~/.zsh/zsh-autocomplete`. + +Manjaro: +- Smoke: current `setup.sh` detects `/etc/manjaro-release`; migrated runner detects `manjaro` and discovers `general/` + `manjaro/` steps. +- Idempotency: `pacman -S --needed`, `yay -S --needed`, yay bootstrap, default shell, ZSH plugin clones, printing/firewall/clamav services, JetBrains Toolbox, Jabba, Joplin, and note steps are safe on second run. +- Assertions: dotfile symlinks; packages from `setup/manjaro/pacman.txt`; AUR install attempts/results from `setup/manjaro/aur.txt`; `yay` availability; ZSH plugin directories; service commands for CUPS/firewall/clamav behave or are recorded as container-limited. + +Fedora Atomic: +- Smoke: current `setup.sh` chooses Atomic when `rpm-ostree` is present; migrated runner detects `fedora-atomic` and discovers `general/` + `fedora-atomic/` steps. +- Idempotency: `rpm-ostree` upgrade/layering, default shell, ZSH plugins, tealdeer/Vim setup, Flatpak remote/app installation, toolbox creation, toolbox package installs, and each toolbox extra step are safe on repeat. +- Assertions: host package list from `setup/fedora-atomic/rpm-ostree.txt`; Flatpaks from `setup/fedora-atomic/flatpak.txt`; toolboxes from `setup/fedora-atomic/toolboxes.txt`; per-toolbox packages from `setup/fedora-atomic/toolboxes/*.txt`; extras such as LTEX LS path, `ktlint`, `swiftlint`, Jabba/Pyenv/NVM directories when feasible. + +macOS mock: +- Smoke: mocked `uname -s` returns `Darwin`; current `setup.sh` dispatches to `setup.macos.sh`; migrated runner detects `macos` and discovers `general/` + `macos/` steps. +- Idempotency: mocked Homebrew install path, `brew bundle`, SSH agent/keychain calls, shared Vim directory setup, and macOS-specific Vim theme logic are repeat-safe. +- Assertions: expected symlinks; `brew bundle --file=setup/macos/Brewfile` invocation; mocked `ssh-add --apple-use-keychain`; no Linux OS-specific steps run. + +### Runner-Specific Tests +- `./setup.sh --help` documents OS detection, selection flags, and examples. +- `./setup.sh --list` prints ordered discovered steps with help descriptions. +- `./setup.sh --only general/01-symlinks.sh` runs exactly that step. +- `./setup.sh --exclude fedora/14-tailscale.sh` runs all applicable Fedora steps except Tailscale services. +- `./setup.sh --interactive` uses `fzf --multi` when present. +- `./setup.sh --interactive` falls back gracefully when `fzf` is absent. +- Unknown step selectors fail with a clear error. +- Non-executable or malformed step scripts are skipped or fail according to documented runner behavior. + +### Baseline Artifacts +- Store summaries/logs such as: + - `tests/baselines/fedora.txt` + - `tests/baselines/manjaro.txt` + - `tests/baselines/fedora-atomic.txt` + - `tests/baselines/macos.txt` +- Record each target as pass/fail/skip with notes for container limitations. +- Compare post-migration summaries against baseline, accepting intentional differences only when documented. + +# Delivery Steps + +### ✓ Step 1: Build Podman bats test harness for current scripts +A Makefile-driven Podman and bats-core matrix exists and can run against the current setup scripts. + +- Add `Makefile` targets for `test-fedora`, `test-manjaro`, `test-fedora-atomic`, `test-macos`, aggregate `test`, `baseline`, and `compare-baseline`. +- Add Containerfiles under `tests/containers/` for Fedora, Manjaro, Fedora Atomic, and macOS mock targets. +- Add shared bats helpers under `tests/bats/helpers/` for command execution, OS simulation, and assertions. +- Add bats smoke, idempotency, and per-OS assertion files that initially invoke the existing `setup.sh` / platform scripts. +- Prefer real package-manager execution in disposable Linux containers; keep macOS mocked and document any Fedora Atomic `rpm-ostree` fallback. + +### ✓ Step 2: Run and record baseline results +Current-script behavior is captured as a non-blocking baseline for all supported OS targets. + +- Run the full Makefile matrix before migration. +- Save pass/fail/skip summaries and relevant logs under `tests/baselines/`. +- Annotate known current limitations such as container `systemctl`, `chsh`, Tailscale, external network installers, macOS mock-only coverage, and any Fedora Atomic `rpm-ostree` constraints. +- Ensure baseline recording does not require all current tests to pass before migration proceeds. + +### ✓ Step 3: Implement setup runner and numbered step structure +The root `setup.sh` becomes an orchestration-only runner and setup logic moves into numbered step scripts. + +- Rewrite `setup.sh` to detect OS, discover `setup/general/*.sh` and `setup//*.sh`, sort steps, apply `--all`, `--only`, `--exclude`, `--interactive`, `--list`, and `--help`, then run each step as a separate process via `presteps` and `run`. +- Create `setup/general/`, `setup/macos/`, `setup/manjaro/`, `setup/fedora/`, and `setup/fedora-atomic/` with executable numbered scripts following the required `presteps` / `help` / `run` dispatch template. +- Add `setup/general/common.bash` as the shared helper library for platform-neutral idempotent primitives; keep it non-executable so the runner does not treat it as a step. +- Preserve explicit selection semantics so include-only runs exactly the requested discovered steps. +- Move current symlink, git-filter, shared Vim directory, manifest-reading, and guarded clone primitives into `setup/general/` where possible without leaving setup logic in the runner. +- Keep Flatpak, shell mutation, package-manager, installer, and downloader behavior in OS-specific steps or OS-specific `common.bash` helper companions. + +### ✓ Step 4: Port OS setup logic and manifests +All current macOS, Fedora, Fedora Atomic, and Manjaro setup behavior is represented as idempotent numbered steps with local companion data. + +- Move package manifests from `packages/` into their corresponding `setup//` directories. +- Add `setup/macos/common.bash`, `setup/fedora/common.bash`, `setup/fedora-atomic/common.bash`, and `setup/manjaro/common.bash` for platform-dependent helpers reused within each OS. +- Port Homebrew/Brewfile, SSH agent/keychain, and macOS Vim theme logic into small `setup/macos/` steps that reuse only platform-neutral helpers from `general/` and keep macOS installer/downloader guards local. +- Split Fedora logic into focused `dnf`, COPR, Flatpak runtime, Flatpak apps, default shell, ZSH plugins, tealdeer, JetBrains Toolbox, Proton Bridge, Bun, Junie, and Tailscale steps with guards for repeat runs. +- Split Fedora Atomic logic into focused `rpm-ostree` upgrade, host packages, default shell, ZSH plugins, tealdeer, Flatpak remote, Flatpak apps, toolbox creation, toolbox packages, and individual toolbox-extra steps with idempotency checks. +- Split Manjaro logic into focused `pacman`, yay bootstrap, AUR, default shell, ZSH plugins, printing, firewall, ClamAV, JetBrains Toolbox, Jabba, Joplin, Cisco note, and Celeste note steps. +- Remove obsolete root platform scripts and the old `packages/` structure after parity is achieved. + +### ✓ Step 5: Validate migrated architecture and update documentation +The migrated setup system is tested against the recorded baseline and documented for future maintenance. + +- Re-run the same Makefile test matrix after migration. +- Compare results to `tests/baselines/`, documenting expected differences and regressions. +- Update `README.md` to describe the new `setup/` layout, step contract, step selection flags, interactive mode, package manifest locations, test harness, and idempotency expectations. +- Update `.gitignore` only for generated test logs/artifacts that should not be tracked. +- Ensure all step scripts are executable and that malformed or non-executable steps are handled according to runner documentation. \ No newline at end of file diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..50f4c61 --- /dev/null +++ b/Makefile @@ -0,0 +1,122 @@ +# Podman + bats-core test harness for the OS setup system. +# +# Targets: +# make build build all container images +# make test-fedora run bats in a disposable Fedora container +# make test-manjaro run bats in a disposable Manjaro container +# make test-fedora-atomic run bats in a Fedora Atomic (mocked rpm-ostree) container +# make test-macos run bats in a mocked macOS container +# make test run the full matrix +# make baseline run the matrix and record results under tests/baselines/ +# make compare-baseline re-run the matrix and diff against the recorded baseline + +PODMAN ?= podman +BATS ?= bats +IMAGE_PREFIX ?= setup-test +REPO_ROOT := $(abspath $(dir $(abspath $(lastword $(MAKEFILE_LIST))))) +WORKSPACE := /workspace + +# The workspace contains user-owned dotfiles that must not be relabeled on an +# enforcing SELinux host. Disable labeling for the disposable test container; +# other hosts retain Podman's private bind-mount label. +SELINUX_STATE := $(shell getenforce 2>/dev/null || true) +ifeq ($(SELINUX_STATE),Enforcing) +PODMAN_SECURITY_OPTS ?= --security-opt label=disable +WORKSPACE_MOUNT := $(REPO_ROOT):$(WORKSPACE) +else +PODMAN_SECURITY_OPTS ?= +WORKSPACE_MOUNT := $(REPO_ROOT):$(WORKSPACE):Z +endif + +# bats files executed per target (paths relative to the repo root / WORKDIR) +BATS_COMMON := tests/bats/smoke.bats tests/bats/idempotency.bats tests/bats/git-filters.bats +BATS_FEDORA := $(BATS_COMMON) tests/bats/assertions-fedora.bats tests/bats/ssh-pkcs11-fedora.bats +BATS_MANJARO := $(BATS_COMMON) tests/bats/assertions-manjaro.bats +BATS_ATOMIC := $(BATS_COMMON) tests/bats/assertions-fedora-atomic.bats +BATS_MACOS := $(BATS_COMMON) tests/bats/assertions-macos.bats + +OS_LIST := fedora manjaro fedora-atomic macos + +.PHONY: build $(addprefix build-,$(OS_LIST)) \ + test $(addprefix test-,$(OS_LIST)) \ + baseline compare-baseline + +# --------------------------------------------------------------------------- +# Image builds +# --------------------------------------------------------------------------- +build: $(addprefix build-,$(OS_LIST)) + +build-fedora: + $(PODMAN) build -t $(IMAGE_PREFIX)/fedora -f tests/containers/Containerfile.fedora . + +build-manjaro: + $(PODMAN) build -t $(IMAGE_PREFIX)/manjaro -f tests/containers/Containerfile.manjaro . + +build-fedora-atomic: + $(PODMAN) build -t $(IMAGE_PREFIX)/fedora-atomic -f tests/containers/Containerfile.fedora-atomic . + +build-macos: + $(PODMAN) build -t $(IMAGE_PREFIX)/macos -f tests/containers/Containerfile.macos-mock . + +# --------------------------------------------------------------------------- +# Runner macro: $(call run_bats,,) +# --------------------------------------------------------------------------- +define run_bats + $(PODMAN) run --rm \ + $(PODMAN_SECURITY_OPTS) \ + -v $(WORKSPACE_MOUNT) \ + -e HOME=/home/tester \ + -e TEST_OS=$(1) \ + --user tester \ + -w $(WORKSPACE) \ + $(IMAGE_PREFIX)/$(1) \ + $(BATS) --formatter tap $(2) +endef + +# --------------------------------------------------------------------------- +# Per-OS test targets +# --------------------------------------------------------------------------- +test: $(addprefix test-,$(OS_LIST)) + +test-fedora: build-fedora + $(call run_bats,fedora,$(BATS_FEDORA)) + +test-manjaro: build-manjaro + $(call run_bats,manjaro,$(BATS_MANJARO)) + +test-fedora-atomic: build-fedora-atomic + $(call run_bats,fedora-atomic,$(BATS_ATOMIC)) + +test-macos: build-macos + $(call run_bats,macos,$(BATS_MACOS)) + +# --------------------------------------------------------------------------- +# Baseline recording (non-blocking) and comparison +# --------------------------------------------------------------------------- +baseline: + @mkdir -p tests/baselines + @for os in $(OS_LIST); do \ + echo "==> Recording baseline: $$os"; \ + { echo "# Baseline: $$os"; \ + echo "# recorded: $$(date -u +%Y-%m-%dT%H:%M:%SZ)"; \ + echo "# host: $$(uname -srm)"; \ + echo; } > tests/baselines/$$os.txt; \ + $(MAKE) test-$$os >> tests/baselines/$$os.txt 2>&1; \ + echo "# exit=$$?" >> tests/baselines/$$os.txt; \ + done + @echo "==> Baselines written to tests/baselines/" + +compare-baseline: + @mkdir -p tests/baselines/current + @for os in $(OS_LIST); do \ + echo "==> Re-running: $$os"; \ + { echo "# Current: $$os"; \ + echo "# recorded: $$(date -u +%Y-%m-%dT%H:%M:%SZ)"; \ + echo; } > tests/baselines/current/$$os.txt; \ + $(MAKE) test-$$os >> tests/baselines/current/$$os.txt 2>&1; \ + echo "# exit=$$?" >> tests/baselines/current/$$os.txt; \ + done + @for os in $(OS_LIST); do \ + echo "===== diff: $$os (baseline -> current) ====="; \ + diff -u tests/baselines/$$os.txt tests/baselines/current/$$os.txt || true; \ + done diff --git a/README.md b/README.md index c0609c9..17550d8 100644 --- a/README.md +++ b/README.md @@ -8,24 +8,28 @@ Cross-platform dotfiles repository supporting **macOS**, **Fedora**, **Fedora At ```bash git clone ~/config ``` -2. **Configure git filters** (required before any other git operations): +2. **Run the setup script**: ```bash - cd ~/config && ./setup.git-filters.sh + cd ~/config && ./setup.sh ``` -3. **Run the setup script**: + This detects your OS, discovers applicable step scripts, and runs them in order. + + **Selective runs**: ```bash - ./setup.sh + ./setup.sh --list # list discovered steps + ./setup.sh --only general/01-symlinks.sh # run a single step + ./setup.sh --exclude fedora/14-tailscale.sh # skip a step + ./setup.sh --interactive # choose steps with fzf ``` - This symlinks config files into `$HOME`, installs packages, and runs platform-specific setup. ## Supported Platforms -| OS | Setup Script | Package Managers | Status | +| OS | Step Directory | Package Managers | Status | |---|---|---|---| -| **macOS** | `setup.macos.sh` | Homebrew | ✅ Active | -| **Fedora** | `setup.fedora.sh` | dnf, COPR, Flatpak | ✅ Active | -| **Fedora Atomic** | `setup.atomic-fedora.sh` | rpm-ostree, Flatpak, Toolbx | 🧪 Untested | -| **Manjaro** | `setup.manjaro.sh` | pacman, AUR (yay) | 🧪 Untested | +| **macOS** | `setup/macos/` | Homebrew | ✅ Active | +| **Fedora** | `setup/fedora/` | dnf, COPR, Flatpak | ✅ Active | +| **Fedora Atomic** | `setup/fedora-atomic/` | rpm-ostree, Flatpak, Toolbx | ✅ Tested (only Test Suit) | +| **Manjaro** | `setup/manjaro/` | pacman, AUR (yay) | ✅ Tested (only Test Suit) | ## Repository Layout @@ -34,52 +38,56 @@ config/ ├── .gitattributes # Git filter assignments (PKCS11, API keys) ├── .gitignore ├── README.md -├── setup.sh # Main entry point: symlinks + platform dispatch -├── setup.macos.sh # macOS: Homebrew, SSH agent, keychain -├── setup.fedora.sh # Fedora: dnf, Flatpak, ZSH plugins, toolbox -├── setup.atomic-fedora.sh # Fedora Atomic: rpm-ostree, toolboxes -├── setup.manjaro.sh # Manjaro: pacman, AUR, printer, firewall -├── setup.git-filters.sh # One-shot git clean/smudge filter registration +├── Makefile # Podman + bats-core test harness +├── setup.sh # Orchestration-only runner (OS detect + step dispatch) +├── setup/ # Numbered step scripts + manifests +│ ├── general/ # OS-agnostic steps (symlinks, git filters, vim base) +│ │ ├── common.bash # Platform-neutral helper library (non-executable) +│ │ ├── 01-symlinks.sh +│ │ ├── 02-git-filters.sh +│ │ └── 03-vim-base.sh +│ ├── macos/ # macOS steps + Brewfile +│ ├── fedora/ # Fedora steps + dnf/flatpak/copr manifests +│ ├── fedora-atomic/ # Fedora Atomic steps + rpm-ostree/toolbox manifests +│ └── manjaro/ # Manjaro steps + pacman/aur manifests +├── tests/ # Podman + bats-core test matrix ├── zshrc # ZSH shell configuration ├── gitconfig # Git global configuration ├── vimrc # Vim configuration ├── vim/ # Vim custom color scheme + persistent undo ├── nvim/ # Neovim (lazy.nvim, 27 plugins, LSP) +├── kitty/ # Kitty terminal emulator ├── ghostty/ # Ghostty terminal emulator ├── lazygit/ # Lazygit TUI keybinding overrides ├── vscodium/ # VSCodium (base+overlay settings pattern) ├── ssh/ # SSH config, host stanzas, YubiKey PKCS11 ├── scripts/ # Custom CLI tools (project, work-finder) -├── packages/ # Per-platform package manifests ├── Nextcloud/ # Nextcloud desktop client config └── junie/ # Junie AI assistant settings ``` | Path | Purpose | |---|---| -| `setup.sh` | Main entry point. Creates symlinks from repo to `$HOME` (e.g. `zshrc` → `~/.zshrc`, `nvim/` → `~/.config/nvim`), detects OS via `uname -s` and `/etc/*-release`, then delegates to the matching platform script. | -| `setup.macos.sh` | macOS setup: installs Homebrew + Brewfile packages, configures SSH agent with `ssh-add -A`, sets up keychain for SSH passphrases, installs vim theme. | -| `setup.fedora.sh` | Fedora setup: installs dnf groups + Flatpaks + COPR repos, ZSH plugins (autosuggestions, syntax-highlighting), tealdeer, toolbox, protonmail bridge, bun, junie, tailscale. | -| `setup.atomic-fedora.sh` | Fedora Atomic setup: rpm-ostree layering, Flatpaks, toolbox containers with per-toolbox package manifests (cli-dev, cpp-dev, latex, mobile). | -| `setup.manjaro.sh` | Manjaro setup: pacman + AUR via yay, ZSH plugins, CUPS printer, firewall (ufw), clamav, external install scripts (JetBrains Toolbox, Jabba, Joplin, Cisco, Celeste). | -| `setup.git-filters.sh` | Registers `scrub-apikey` and `pkcs11-provider` git clean/smudge filters. Called automatically by `setup.sh`. Run manually after a fresh clone before any other git operations. | -| `zshrc` | ZSH config: OS/hardware detection, history settings, aliases, platform-aware clip/clippaste helpers, completion system, starship prompt, version managers (NVM, JABBA, PYENV, RBENV, bun), ZSH plugins, custom script shell-integration. | +| `setup.sh` | Orchestration-only runner. Detects OS, discovers numbered step scripts under `setup/general/` and `setup//`, applies selection filters (`--all`, `--only`, `--exclude`, `--interactive`), and runs each step as a separate process via `presteps` then `run`. No setup logic lives here. | +| `setup/general/` | OS-agnostic steps that run first on every platform: symlink dotfiles, register git filters, create shared editor directories. `common.bash` provides platform-neutral primitives (logging, symlink helpers, git clone guards, manifest parsing). | +| `setup//` | Platform-specific numbered steps with companion manifests and a `common.bash` helper library. Steps are idempotent — safe to run repeatedly. | +| `zshrc` | ZSH config: OS/hardware detection, history settings, aliases, platform-aware clip/clippaste helpers, completion system, Starship prompt with custom fallback, version managers (NVM, JABBA, PYENV, RBENV, bun), ZSH plugins, custom script shell-integration. | | `gitconfig` | Git config: GPG SSH signing, codium/vscode as difftool/mergetool, LFS, pull rebase, credential cache. | | `vimrc` | Vim config: persistent undo, custom theme, indentation, whitespace display, statusline. | | `vim/` | Vim custom color scheme (`cyberpunk_scarlet_protocol_adjusted.vim`) and persistent undo directory. | | `nvim/` | Neovim config: `lazy.nvim` package manager, 27 plugins (LSP, Telescope, Treesitter, lualine, nvim-tree, harpoon, trouble, which-key, vimtex, Java JDTLS, Godot LSP, GPTModels, etc.). | +| `kitty/` | Kitty terminal emulator: preferred cross-platform terminal for macOS, GNOME, and KDE with Cyberpunk Scarlet Protocol theme, xterm-compatible `TERM`, Swiss-friendly shortcuts, tabs, splits, clipboard, and shell integration. | | `ghostty/` | Ghostty terminal emulator: appearance, Swiss keyboard keybindings, custom Cyberpunk Scarlet Protocol theme. | | `lazygit/` | Lazygit TUI: custom keybinding overrides. | | `vscodium/` | VSCodium: base+overlay settings (`settings.base.json` + platform-specific overlays), extensions list, `code export`/`code import` zsh functions. | | `ssh/` | SSH config: `config` entry point (Include, ControlMaster, keychain), `config.d/*` host stanzas (private, homelab, infra, zhaw), YubiKey PKCS11 provider filter. | | `scripts/` | Custom CLI tools: `project` (project directory switcher), `work-finder` (git/file activity scanner). Both support `--shell-integration` for zsh wrapper + completion generation. | -| `packages/` | Per-platform package manifests: `macos/Brewfile`, `fedora/` (dnf, flatpak, copr), `fedora-atomic/` (rpm-ostree, flatpak, toolboxes/), `manjaro/` (pacman, aur, external/). | | `Nextcloud/` | Nextcloud desktop client config (`nextcloud.cfg`) and sync-exclude patterns (`sync-exclude.lst`). | | `junie/` | Junie AI assistant: `settings.json`, model configs with API key scrub filter. | ## Git Filters -This repo uses two git clean/smudge filters, registered by `setup.git-filters.sh`: +This repo uses two git clean/smudge filters, registered by `setup/general/02-git-filters.sh`: - **`scrub-apikey`** — redacts API keys in `junie/models/*.json` on commit (clean only; smudge passes through unchanged). - **`pkcs11-provider`** — tokenizes PKCS#11 provider paths in `ssh/config.d/*` on commit (`@YKCS11@`, `@OPENSC@`) and resolves them to the current platform's real paths on checkout. Provider paths are defined in `ssh/providers.mac` and `ssh/providers.fedora`. @@ -100,11 +108,11 @@ rewrites provider paths on commit/checkout. Any path under `ssh/config.d/` is piped through the `pkcs11-provider` filter on its way in/out of the object database. -2. **`setup.git-filters.sh`** — run once per clone (also called by `setup.sh`). +2. **`setup/general/02-git-filters.sh`** — run once per clone (also called by `setup.sh`). It registers the filter with git: ``` - git config filter.pkcs11-provider.clean "$REPO_DIR/ssh/pkcs11-filter.sh clean" - git config filter.pkcs11-provider.smudge "$REPO_DIR/ssh/pkcs11-filter.sh smudge" + git config filter.pkcs11-provider.clean "ssh/pkcs11-filter.sh clean" + git config filter.pkcs11-provider.smudge "ssh/pkcs11-filter.sh smudge" git config filter.pkcs11-provider.required true ``` `required true` means git will fail rather than silently skip the filter. @@ -165,9 +173,7 @@ directory anymore, and no host duplication. Host stanzas live once in stored blob. - **`git checkout`/`git clone` on another machine** → smudge filter swaps tokens → that machine's real paths in the working tree. -- **Switch platforms** → just re-run `./setup.git-filters.sh` (already in - `setup.sh`) and `git checkout -- ssh/config.d/` to re-smudge with the new - platform's paths. +- **Switch platforms** → run `./setup.sh --only general/02-git-filters.sh` (or the full `./setup.sh`) and `git checkout -- ssh/config.d/` to re-smudge with the new platform's paths. #### Caveats @@ -179,92 +185,155 @@ directory anymore, and no host duplication. Host stanzas live once in ## Setup System -### setup.sh - -The main entry point. It performs two jobs: - -1. **Symlink creation**: links repo files into `$HOME`: - - `zshrc` → `~/.zshrc` - - `gitconfig` → `~/.gitconfig` - - `vimrc` → `~/.vimrc` - - `nvim/` → `~/.config/nvim` - - `vim/` → `~/.vim` - - `ghostty/` → `~/Library/Application Support/com.mitchellh.ghostty/config` (macOS) - or `~/.config/ghostty` (Linux) - - `lazygit/` → `~/.config/lazygit` (Linux) or `~/Library/Application Support/lazygit` (macOS) - - `vscodium/` → VSCodium/Code user config directory (platform-specific paths) - - `ssh/` → `~/.ssh` (including `config`, `config.d/`, `known_hosts`) - - `Nextcloud/` → Nextcloud config directory - -2. **Platform dispatch**: detects OS and delegates to the appropriate platform script. - -### setup.macos.sh - -- Installs **Homebrew** if not present -- Installs packages from `packages/macos/Brewfile` (`brew bundle`) -- Configures **SSH agent** with `ssh-add -A` (adds all identities from keychain) -- Sets up **SSH keychain** integration via `UseKeychain yes` in `~/.ssh/config` -- Installs the **vim theme** (copies `cyberpunk_scarlet_protocol_adjusted.vim` to Homebrew vim colors) -- Runs `setup.git-filters.sh` (via `setup.sh`) - -### setup.fedora.sh - -- Installs **dnf** packages from `packages/fedora/dnf.txt` -- Enables **COPR** repos from `packages/fedora/copr.txt` -- Installs **Flatpak** packages from `packages/fedora/flatpak.txt` (Flathub) -- Installs **ZSH plugins**: `zsh-autosuggestions`, `zsh-syntax-highlighting`, `zsh-autocomplete` -- Installs **tealdeer** (simplified man pages) and updates its cache -- Sets up **toolbox** container for CLI dev -- Installs **protonmail bridge** (dnf + initial setup) -- Installs **bun** (JavaScript runtime) via curl -- Installs **junie** CLI -- Enables and starts **tailscaled** -- Sets up **vim undo** directory - -### setup.atomic-fedora.sh - -- **rpm-ostree** layering from `packages/fedora-atomic/rpm-ostree.txt` -- **Flatpak** packages from `packages/fedora-atomic/flatpak.txt` -- **Toolbox** containers with per-toolbox manifests: - - `cli-dev` — CLI development tools (`packages/fedora-atomic/toolboxes/cli-dev.txt`) - - `cpp-dev` — C++ development tools (`packages/fedora-atomic/toolboxes/cpp-dev.txt`) - - `latex` — LaTeX toolchain (`packages/fedora-atomic/toolboxes/latex.txt`) - - `mobile` — Mobile development tools (`packages/fedora-atomic/toolboxes/mobile.txt`) -- **1Password** and **1Password CLI** (rpm-ostree) -- Sets up **vim undo** directory - -### setup.manjaro.sh - -- Installs **pacman** packages from `packages/manjaro/pacman.txt` -- Installs **AUR** packages via **yay** from `packages/manjaro/aur.txt` -- Installs **ZSH plugins** (same as Fedora) -- Enables and starts **CUPS** (printing) -- Configures **firewall** (ufw) with basic rules (SSH, KDE Connect, syncthing, printing) -- Installs **clamav** (antivirus) and updates virus definitions -- Runs **external scripts** from `packages/manjaro/external/`: - - `10-jetbrains-toolbox.sh` — JetBrains Toolbox - - `20-jabba.sh` — Jabba JDK version manager - - `30-joplin.sh` — Joplin note-taking app - - `40-cisco-note.sh` — Cisco Packet Tracer - - `50-celeste-note.sh` — Celeste sync client -- Sets up **vim undo** directory - -### Package Manifests (packages/) - -Each platform has its own package list files. The setup scripts read these to install packages. +### Architecture + +The setup system uses a **numbered step-script architecture**. The root `setup.sh` is an orchestration-only runner — it detects the OS, discovers step scripts, and dispatches them. No setup logic lives in the runner itself. + +**Execution order**: `setup/general/` steps run first (OS-agnostic), then the detected OS-specific directory (`setup//`). Within each directory, scripts are sorted lexically by filename. + +### Step Contract + +Every step script dispatches on `$1` to three functions: + +- **`presteps`** — validate prerequisites (fail fast with actionable messages). Never mutates state. +- **`help`** — print a short description of what the step does. +- **`run`** — idempotent setup logic. Safe to run repeatedly. + +Steps are executed as separate processes (`./step.sh presteps` then `./step.sh run`). Helper files (`common.bash`) are non-executable and are not discovered as steps. + +### CLI Selection Modes + +| Flag | Behavior | +|---|---| +| (default) / `--all` | Run all discovered steps | +| `--only SEL,...` | Run exactly the selected step IDs | +| `--exclude SEL,...` | Run all discovered steps except selected | +| `--interactive` | Choose steps with `fzf --multi` (falls back to flags if fzf absent) | +| `--list` | List discovered steps with help text | +| `--help` | Show usage | + +Selectors match in order: `/`, ``, ``. Examples: +```bash +./setup.sh --only general/01-symlinks.sh +./setup.sh --only fedora/06-flatpak-apps.sh,fedora/08-zsh-plugins.sh +./setup.sh --exclude fedora/14-tailscale.sh +``` + +### Idempotency + +Every step is **idempotent** — running the full setup or any subset on an already-configured system is safe: +- Symlinks are only changed when the target differs; backups are created once. +- Package steps query installed state before installing (`dnf install -y`, `pacman -S --needed`, `flatpak list --app`). +- Git clones skip existing directories. +- Download/install steps check for the final binary before downloading. +- Service steps check current state before calling `systemctl`. + +### General Steps (`setup/general/`) + +OS-agnostic steps that run first on every platform: + +| Step | Description | +|---|---| +| `01-symlinks.sh` | Symlink dotfiles (zshrc, vimrc, gitconfig, nvim, lazygit, kitty, ghostty, ssh, etc.) into `$HOME` | +| `02-git-filters.sh` | Register `pkcs11-provider` and `scrub-apikey` git clean/smudge filters | +| `03-vim-base.sh` | Create shared editor directories (`~/.vim/undo`) | + +`common.bash` provides platform-neutral primitives: `ensure_symlink`, `ensure_dir`, `ensure_git_clone`, `ensure_git_config`, `ensure_line_present`, `read_manifest`, `command_exists`, `require_command`. + +### macOS Steps (`setup/macos/`) + +| Step | Description | +|---|---| +| `01-homebrew.sh` | Install Homebrew if not present | +| `02-brew-bundle.sh` | Install packages from `setup/macos/Brewfile` via `brew bundle` | +| `03-ssh-agent.sh` | Start ssh-agent if not running | +| `04-ssh-keychain.sh` | Add SSH keys to Apple keychain | +| `05-vim-theme.sh` | Clone Dracula vim theme | +| `06-junie.sh` | Install Junie CLI | +| `07-waveforms.sh` | Download and install Digilent WaveForms from the official `.dmg` (not in Brewfile; falls back to the browser if Cloudflare blocks `curl`) | + +### Fedora Steps (`setup/fedora/`) + +| Step | Description | +|---|---| +| `01-system-update.sh` | `sudo dnf -y upgrade --refresh` | +| `02-copr-repos.sh` | Enable COPR repos from `copr.txt` | +| `03-dnf-packages.sh` | Install dnf packages from `dnf.txt` | +| `04-copr-packages.sh` | Install COPR-dependent packages (lazygit, scrcpy, codium, steam, proton-vpn) | +| `05-flatpak-runtime.sh` | Install Flatpak + ensure Flathub remote | +| `06-flatpak-apps.sh` | Install Flatpak apps from `flatpak.txt` | +| `07-default-shell.sh` | Change default shell to zsh | +| `08-zsh-plugins.sh` | Clone ZSH plugins (autosuggestions, syntax-highlighting, autocomplete) | +| `09-tealdeer.sh` | Create tealdeer config + update tldr cache | +| `10-jetbrains-toolbox.sh` | Download JetBrains Toolbox | +| `11-proton-bridge.sh` | Install Proton Mail Bridge RPM | +| `12-bun.sh` | Install Bun via official installer | +| `13-junie.sh` | Install Junie CLI | +| `14-tailscale.sh` | Enable and start Tailscale | + +### Fedora Atomic Steps (`setup/fedora-atomic/`) + +| Step | Description | +|---|---| +| `01-system-upgrade.sh` | `sudo rpm-ostree upgrade` | +| `02-host-packages.sh` | Layer host packages from `rpm-ostree.txt` | +| `03-default-shell.sh` | Change default shell to zsh | +| `04-zsh-plugins.sh` | Clone ZSH plugins | +| `05-tealdeer.sh` | Create tealdeer config + update tldr cache | +| `06-flatpak-remote.sh` | Ensure Flatpak + Flathub remote | +| `07-flatpak-apps.sh` | Install Flatpak apps from `flatpak.txt` | +| `08-toolbox-create.sh` | Create toolboxes from `toolboxes.txt` | +| `09-toolbox-packages.sh` | Install packages in each toolbox | +| `10-toolbox-latex.sh` | Install LTEX LS in latex toolbox | +| `11-toolbox-mobile.sh` | Install ktlint + SwiftLint in mobile toolbox | +| `12-toolbox-cli-dev.sh` | Install Jabba, Pyenv, NVM in cli-dev toolbox | +| `99-reboot-notice.sh` | Print reboot reminder | + +### Manjaro Steps (`setup/manjaro/`) + +| Step | Description | +|---|---| +| `01-system-update.sh` | `sudo pacman -Syu --noconfirm` | +| `02-pacman-packages.sh` | Install pacman packages from `pacman.txt` | +| `03-yay-bootstrap.sh` | Bootstrap yay (AUR helper) | +| `04-aur-packages.sh` | Install AUR packages from `aur.txt` | +| `05-default-shell.sh` | Change default shell to zsh | +| `06-zsh-plugins.sh` | Clone ZSH plugins | +| `07-printing.sh` | Enable CUPS printing service | +| `08-firewall.sh` | Enable nftables + ufw | +| `09-clamav.sh` | Enable ClamAV freshclam | +| `10-jetbrains-toolbox.sh` | Download JetBrains Toolbox | +| `11-jabba.sh` | Install Jabba (Java version manager) | +| `12-joplin.sh` | Install Joplin note-taking app | +| `13-cisco-note.sh` | Cisco AnyConnect VPN note | +| `14-celeste-note.sh` | Celeste cloud sync note | + +### Package Manifests + +Each platform's manifests live alongside their step scripts in `setup//`. | Manifest | Format | Export command | |---|---|---| -| `packages/macos/Brewfile` | Homebrew Bundle | `brew bundle dump --file=packages/macos/Brewfile --force` | -| `packages/fedora/dnf.txt` | One package per line | `rpm -qa --qf "%{NAME}\n" \| grep -v -f <(rpm -qa --qf "%{NAME}\n" --group "Core") \| sort > packages/fedora/dnf.txt` | -| `packages/fedora/copr.txt` | One COPR repo per line | (manual) | -| `packages/fedora/flatpak.txt` | One app ID per line | `flatpak list --app --columns=application \| tail -n +1 > packages/fedora/flatpak.txt` | -| `packages/fedora-atomic/rpm-ostree.txt` | One package per line | `rpm-ostree status --json \| jq -r '.deployments[0]["requested-packages"][]'` | -| `packages/fedora-atomic/flatpak.txt` | One app ID per line | Same as Fedora flatpak | -| `packages/fedora-atomic/toolboxes.txt` | List of toolbox names | (manual) | -| `packages/fedora-atomic/toolboxes/*.txt` | Per-toolbox dnf packages | (manual per toolbox) | -| `packages/manjaro/pacman.txt` | One package per line | `pacman -Qqen \| sort > packages/manjaro/pacman.txt` | -| `packages/manjaro/aur.txt` | One package per line | `pacman -Qqem \| sort > packages/manjaro/aur.txt` | +| `setup/macos/Brewfile` | Homebrew Bundle | `brew bundle dump --file=setup/macos/Brewfile --force` | +| `setup/fedora/dnf.txt` | One package per line | `dnf repoquery --userinstalled --qf "%{name}\n" \| sort` | +| `setup/fedora/copr.txt` | One COPR repo per line | (manual) | +| `setup/fedora/flatpak.txt` | One app ID per line | `flatpak list --app --columns=application \| sort` | +| `setup/fedora-atomic/rpm-ostree.txt` | One package per line | `rpm-ostree status --json \| jq -r '.deployments[0]["requested-packages"][]'` | +| `setup/fedora-atomic/flatpak.txt` | One app ID per line | Same as Fedora flatpak | +| `setup/fedora-atomic/toolboxes.txt` | List of toolbox names | (manual) | +| `setup/fedora-atomic/toolboxes/*.txt` | Per-toolbox dnf packages | (manual per toolbox) | +| `setup/manjaro/pacman.txt` | One package per line | `pacman -Qqen \| sort` | +| `setup/manjaro/aur.txt` | One package per line | `pacman -Qqem \| sort` | + +### Test Harness + +A Podman + bats-core matrix validates the setup system. See `tests/README.md` for details. + +```bash +make build # build all container images +make test-fedora # run Fedora tests +make test # run the full matrix +``` ## Shell Configuration (zshrc) @@ -310,7 +379,7 @@ The `zshrc` is the most complex config file. It handles: ### Prompt -Uses **Starship** prompt (`starship.toml` not in this repo). Falls back gracefully if not installed. +Uses **Starship** prompt with a full-featured `starship.toml` in this repo. Falls back gracefully to a custom prompt if Starship is not installed. ### Version Managers @@ -496,6 +565,14 @@ Uses **lazy.nvim** — bootstrapped from `lazy_init.lua`, which auto-installs la - **LaTeX**: `vimtex` with forward/inverse search - **Godot**: GDScript language server configured in `gdscript.lua` +## Kitty Configuration + +- **Preferred terminal**: cross-platform replacement for iTerm2 on macOS and the default GNOME/KDE terminals on Linux +- **Compatibility**: sets `TERM=xterm-256color` instead of `xterm-kitty` so SSH hosts, serial consoles, rescue shells, `vim`, `systemctl`, and other TUI tools work without Kitty terminfo installed remotely +- **Appearance**: custom Cyberpunk Scarlet Protocol theme matched to the existing Ghostty/Vim colors +- **Keyboard**: Apple-style tab/split/clipboard shortcuts, Swiss-friendly bindings for tab navigation and vertical splits, and Option/Alt word movement +- **Behavior**: shell integration, large scrollback, copy-on-select, quiet bell, tabs, splits, and fullscreen/edit-config shortcuts + ## Ghostty Configuration - **Appearance**: custom dark theme (Cyberpunk Scarlet Protocol), background opacity 0.95 @@ -577,13 +654,21 @@ Both scripts are auto-loaded by `zshrc` via shell integration, so their commands ### Adding Packages -1. Identify the correct platform manifest (see [Package Manifests](#package-manifests-packages) table above). +1. Identify the correct platform manifest (see [Package Manifests](#package-manifests) table above). 2. Add the package name to the appropriate text file (one per line). 3. After installing on the target machine, run the export command to keep the manifest in sync: - - macOS: `brew bundle dump --file=packages/macos/Brewfile --force` - - Fedora: `rpm -qa --qf "%{NAME}\n" | grep -v -f <(rpm -qa --qf "%{NAME}\n" --group "Core") | sort > packages/fedora/dnf.txt` - - Fedora Flatpak: `flatpak list --app --columns=application | tail -n +1 > packages/fedora/flatpak.txt` - - Manjaro: `pacman -Qqen | sort > packages/manjaro/pacman.txt` (official) and `pacman -Qqem | sort > packages/manjaro/aur.txt` (AUR) + - macOS: `brew bundle dump --file=setup/macos/Brewfile --force` + - Fedora: `dnf repoquery --userinstalled --qf "%{name}\n" | sort > setup/fedora/dnf.txt` + - Fedora Flatpak: `flatpak list --app --columns=application | sort > setup/fedora/flatpak.txt` + - Manjaro: `pacman -Qqen | sort > setup/manjaro/pacman.txt` (official) and `pacman -Qqem | sort > setup/manjaro/aur.txt` (AUR) + +### Adding Setup Steps + +1. Create a new numbered `.sh` file in the appropriate `setup//` directory. +2. Follow the step contract: implement `presteps()`, `help()`, and `run()`. +3. Source `setup/general/common.bash` for platform-neutral helpers; source your OS `common.bash` for platform-specific helpers. +4. Make the script executable (`chmod +x`). +5. Ensure `run()` is idempotent — check current state before every mutation. ### Adding SSH Hosts @@ -629,8 +714,9 @@ Both scripts are auto-loaded by `zshrc` via shell integration, so their commands | Pattern | How it works | |---|---| -| **OS detection** | `zshrc` sets `$OS` to `Darwin` or `Linux`; scripted files use `uname -s` | -| **Platform-specific setup** | `setup.sh` dispatches to `setup..sh` | +| **OS detection** | `zshrc` sets `$OS` to `Darwin` or `Linux`; `setup.sh` uses `uname -s` and `/etc/*-release` | +| **Platform-specific setup** | `setup.sh` discovers and runs numbered steps from `setup/general/` then `setup//` | +| **Step contract** | Every step implements `presteps` / `help` / `run`; helpers in `common.bash` | | **Git filters for platform values** | Use clean/smudge filters (`pkcs11-provider` pattern) to keep platform-specific paths tokenized in commits, resolved in working trees | | **Base + overlay settings** | `vscodium/` uses shared `settings.base.json` + platform-specific overlays | | **Provider path tables** | `ssh/providers.mac` / `ssh/providers.fedora` hold only key=value pairs, never hosts | @@ -647,20 +733,9 @@ These are concrete suggestions to improve the config over time. None are blocker ### Medium Priority -- **Unify ZSH plugin installation**: The same three plugins (`zsh-autosuggestions`, `zsh-syntax-highlighting`, `zsh-autocomplete`) are installed separately in `setup.fedora.sh`, `setup.atomic-fedora.sh`, and `setup.manjaro.sh` with duplicate code. Extract into a shared function in `setup.sh` or a `setup.linux-common.sh`. -- **Create `setup.linux-common.sh`**: Shared Linux steps (ZSH plugins, tealdeer, vim undo dir creation, Ghostty Linux config path) are duplicated across the three Linux setup scripts. Extract them into a single file. -- **Clean up Brewfile backups**: `packages/macos/Brewfile.old*` files are tracked. Either delete them or add to `.gitignore`. - -### Low Priority / Nice to Have - - **Add shellcheck CI**: All setup scripts are shell (`sh`/`bash`). A pre-commit hook or CI step running `shellcheck` would catch common issues. - **Untrack `known_hosts.old` and `.netrwhist`**: These auto-generated files are tracked in git but are ephemeral data, not config. Consider removing from tracking or adding to `.gitignore`. -- **Add `Makefile` or `justfile`**: A single entry point for common operations: - - `make setup` / `just setup` - - `make export-packages` / `just export-packages` - - `make update-filters` / `just update-filters` - **Document `code export`/`code import` workflow**: The VSCodium settings sync flow is powerful but not obvious. Consider a dedicated section showing end-to-end usage. -- **Write a `starship.toml`**: The zshrc references Starship prompt but the `starship.toml` isn't in this repo. Adding it would make the prompt portable. ## TODO @@ -676,6 +751,10 @@ These are concrete suggestions to improve the config over time. None are blocker - [x] terminal config (ghostty) - [x] vscode(ium) config (base + overlay) - [x] neovim (lazy.nvim, 27 plugins) +- [ ] Nordic Connect Desktop setup (`setup/macos/08-nrf-connect.sh`) +- [ ] Xcode Additional Tools setup (`setup/macos/11-xcode-additional-tools.sh`) +- [ ] Segger SystemView setup +- [ ] Nordic SDK directories ### Linux @@ -693,7 +772,7 @@ These are concrete suggestions to improve the config over time. None are blocker - [ ] verify PKCS11 provider paths (`providers.fedora`) - [x] neovim config -#### Fedora Atomic (Untested) +#### Fedora Atomic (Tested in containers) - [x] setup script (untested on hardware) - [x] dependency install (rpm-ostree + Flatpak + Toolbx) @@ -707,7 +786,7 @@ These are concrete suggestions to improve the config over time. None are blocker - [ ] verify PKCS11 provider paths (`providers.fedora`) - [x] neovim config -#### Manjaro (Untested) +#### Manjaro (Tested in containers) - [x] setup script (untested on hardware) - [x] dependency install (pacman + AUR) diff --git a/junie/mcp/mcp.json b/junie/mcp/mcp.json new file mode 100644 index 0000000..0a0b8e7 --- /dev/null +++ b/junie/mcp/mcp.json @@ -0,0 +1,11 @@ +{ + "mcpServers": { + "xcode": { + "command": "xcrun", + "args": [ + "mcpbridge" + ], + "enabled": false + } + } +} \ No newline at end of file diff --git a/junie/models/coder-plan-execute.json b/junie/models/coder-plan-execute.json deleted file mode 100644 index c87f802..0000000 --- a/junie/models/coder-plan-execute.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "baseUrl": "http://100.124.60.67:8000/v1/chat/completions", - "id": "lmstudio-community/Qwen2.5-Coder-32B-Instruct-MLX-4bit", - "apiType": "OpenAICompletion", - "apiKey": "REDACTED", - "temperature": 0.2, - "fasterModel": { - "id": "Qwen2.5-Coder-7B-q8-mlx", - "temperature": 0.3 - } -} diff --git a/junie/models/luna.json b/junie/models/luna.json new file mode 100644 index 0000000..ee53cba --- /dev/null +++ b/junie/models/luna.json @@ -0,0 +1,11 @@ +{ + "baseUrl": "https://openrouter.ai/api/v1/responses", + "id": "openai/gpt-5.6-luna-pro", + "apiType": "OpenAIResponses", + "apiKey": "REDACTED", + "temperature": 0.4, + "fasterModel": { + "id": "openai/gpt-5.6-luna", + "temperature": 0.3 + } +} diff --git a/junie/models/minimax.json b/junie/models/minimax.json new file mode 100644 index 0000000..014e26b --- /dev/null +++ b/junie/models/minimax.json @@ -0,0 +1,11 @@ +{ + "baseUrl": "https://openrouter.ai/api/v1/responses", + "id": "minimax/minimax-m3", + "apiType": "OpenAIResponses", + "apiKey": "REDACTED", + "temperature": 0.4, + "fasterModel": { + "id": "minimax/minimax-m3", + "temperature": 0.3 + } +} diff --git a/junie/models/qwable.json b/junie/models/qwable.json index 14696bf..ab50485 100644 --- a/junie/models/qwable.json +++ b/junie/models/qwable.json @@ -1,6 +1,6 @@ { "baseUrl": "http://100.124.60.67:8000/v1/chat/completions", - "id": "Qwen-9B-Claude-Fable-5-1M-MLX-8bit", + "id": "Qwythos-9B-Claude-Mythos-5-1M-MLX-oQ8-mtp", "apiType": "OpenAICompletion", "apiKey": "REDACTED", "temperature": 0.6, diff --git a/junie/models/qwen36-general.json b/junie/models/qwen27dense.json similarity index 100% rename from junie/models/qwen36-general.json rename to junie/models/qwen27dense.json diff --git a/junie/models/thinker-fast-exec.json b/junie/models/thinker-fast-exec.json deleted file mode 100644 index 1b6e0d6..0000000 --- a/junie/models/thinker-fast-exec.json +++ /dev/null @@ -1,11 +0,0 @@ -{ - "baseUrl": "http://100.124.60.67:8000/v1/responses", - "id": "Qwen3.5-27B-Claude-4.6-Opus-Distilled-MLX-4bit", - "apiType": "OpenAIResponses", - "apiKey": "REDACTED", - "temperature": 0.4, - "fasterModel": { - "id": "Llama-3.2-3B-Instruct-4bit", - "temperature": 0.3 - } -} diff --git a/junie/skills/obsidian-plugin-skill b/junie/skills/obsidian-plugin-skill new file mode 120000 index 0000000..6b18e12 --- /dev/null +++ b/junie/skills/obsidian-plugin-skill @@ -0,0 +1 @@ +../vendor/obsidian-plugin-skill \ No newline at end of file diff --git a/junie/skills/raycast-extension-skill b/junie/skills/raycast-extension-skill new file mode 120000 index 0000000..121c8de --- /dev/null +++ b/junie/skills/raycast-extension-skill @@ -0,0 +1 @@ +../vendor/raycast-extension-skill \ No newline at end of file diff --git a/junie/vendor/obsidian-plugin-skill b/junie/vendor/obsidian-plugin-skill new file mode 160000 index 0000000..9b016a2 --- /dev/null +++ b/junie/vendor/obsidian-plugin-skill @@ -0,0 +1 @@ +Subproject commit 9b016a2c0914ba44eba683da5b65cf08b0a4a4aa diff --git a/junie/vendor/raycast-extension-skill b/junie/vendor/raycast-extension-skill new file mode 160000 index 0000000..b640147 --- /dev/null +++ b/junie/vendor/raycast-extension-skill @@ -0,0 +1 @@ +Subproject commit b640147659383065f35f86574dc1f07494b374f5 diff --git a/junie/versions/2206.3/skills/claude-api/LICENSE.txt b/junie/versions/2206.3/skills/claude-api/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/junie/versions/2206.3/skills/claude-api/SKILL.md b/junie/versions/2206.3/skills/claude-api/SKILL.md new file mode 100644 index 0000000..1431d44 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/SKILL.md @@ -0,0 +1,317 @@ +--- +name: claude-api +description: "Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. TRIGGER when: code imports anthropic/@anthropic-ai/sdk; user asks to use the Claude API, Anthropic SDKs, or Managed Agents (/v1/agents, /v1/sessions, /v1/environments). DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks." +license: Complete terms in LICENSE.txt +--- + + +# Building LLM-Powered Applications with Claude + +This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation. + +## Before You Start + +Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — `import openai`, `from openai`, `langchain_openai`, `OpenAI(`, `gpt-4`, `gpt-5`, file names like `agent-openai.py` or `*-generic.py`, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls. + +## Output Requirement + +When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of: + +1. **The official Anthropic SDK** for the project's language (`anthropic`, `@anthropic-ai/sdk`, `com.anthropic.*`, etc.). This is the default whenever a supported SDK exists for the project. +2. **Raw HTTP** (`curl`, `requests`, `fetch`, `httpx`, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK. + +Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims. + +**Never guess SDK usage.** Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the `{lang}/` files in this skill or the official SDK repositories or documentation links listed in `shared/live-sources.md`. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from `shared/live-sources.md` before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK. + +## Defaults + +Unless the user requests otherwise: + +For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string `claude-opus-4-6`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events + +--- + +## Subcommands + +If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every **Subcommands** table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via `/claude-api `. If no table in the document matches, treat the request as normal prose. + + + +--- + +## Language Detection + +Before reading code examples, determine which language the user is working in: + +1. **Look at project files** to infer the language: + + - `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/` + - `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/` + - `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/` + - `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/` + - `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/` + - `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/` + - `*.go`, `go.mod` → **Go** — read from `go/` + - `*.rb`, `Gemfile` → **Ruby** — read from `ruby/` + - `*.cs`, `*.csproj` → **C#** — read from `csharp/` + - `*.php`, `composer.json` → **PHP** — read from `php/` + +2. **If multiple languages detected** (e.g., both Python and TypeScript files): + + - Check which language the user's current file or question relates to + - If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?" + +3. **If language can't be inferred** (empty project, no source files, or unsupported language): + + - Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP + - If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language." + +4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.): + + - Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist + - Offer to show Python or TypeScript examples as reference implementations + +5. **If user needs cURL/raw HTTP examples**, read from `curl/`. + +### Language-Specific Feature Support + +| Language | Tool Runner | Managed Agents | Notes | +| ---------- | ----------- | -------------- | ------------------------------------- | +| Python | Yes (beta) | Yes (beta) | Full support — `@beta_tool` decorator | +| TypeScript | Yes (beta) | Yes (beta) | Full support — `betaZodTool` + Zod | +| Java | Yes (beta) | Yes (beta) | Beta tool use with annotated classes | +| Go | Yes (beta) | Yes (beta) | `BetaToolRunner` in `toolrunner` pkg | +| Ruby | Yes (beta) | Yes (beta) | `BaseTool` + `tool_runner` in beta | +| C# | No | No | Official SDK | +| PHP | Yes (beta) | Yes (beta) | `BetaRunnableTool` + `toolRunner()` | +| cURL | N/A | Yes (beta) | Raw HTTP, no SDK features | + +> **Managed Agents code examples**: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`). Read your language's README plus the language-agnostic `shared/managed-agents-*.md` concept files. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. If a binding you need isn't shown in the README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use cURL-style raw HTTP requests against the API. + +--- + +## Which Surface Should I Use? + +> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration. + +| Use Case | Tier | Recommended Surface | Why | +| ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ | +| Classification, summarization, extraction, Q&A | Single LLM call | **Claude API** | One request, one response | +| Batch processing or embeddings | Single LLM call | **Claude API** | Specialized endpoints | +| Multi-step pipelines with code-controlled logic | Workflow | **Claude API + tool use** | You orchestrate the loop | +| Custom agent with your own tools | Agent | **Claude API + tool use** | Maximum flexibility | +| Server-managed stateful agent with workspace | Agent | **Managed Agents** | Anthropic runs the loop and hosts the tool-execution sandbox | +| Persisted, versioned agent configs | Agent | **Managed Agents** | Agents are stored objects; sessions pin to a version | +| Long-running multi-turn agent with file mounts | Agent | **Managed Agents** | Per-session containers, SSE event stream, Skills + MCP | + +> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution). + +> **Third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry):** Managed Agents is **not available** on Bedrock, Vertex, or Foundry. If you are deploying through any third-party provider, use **Claude API + tool use** for all use cases — including ones where Managed Agents would otherwise be the recommended surface. + +### Decision Tree + +``` +What does your application need? + +0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry? + └── Yes → Claude API (+ tool use for agents) — Managed Agents is 1P only. + No → continue. + +1. Single LLM call (classification, summarization, extraction, Q&A) + └── Claude API — one request, one response + +2. Do you want Anthropic to run the agent loop and host a per-session + container where Claude executes tools (bash, file ops, code)? + └── Yes → Managed Agents — server-managed sessions, persisted agent configs, + SSE event stream, Skills + MCP, file mounts. + Examples: "stateful coding agent with a workspace per task", + "long-running research agent that streams events to a UI", + "agent with persisted, versioned config used across many sessions" + +3. Workflow (multi-step, code-orchestrated, with your own tools) + └── Claude API with tool use — you control the loop + +4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute) + └── Claude API agentic loop (maximum flexibility) +``` + +### Should I Build an Agent? + +Before choosing the agent tier, check all four criteria: + +- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF") +- **Value** — Does the outcome justify higher cost and latency? +- **Viability** — Is Claude capable at this task type? +- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback) + +If the answer is "no" to any of these, stay at a simpler tier (single call or workflow). + +--- + +## Architecture + +Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs. + +**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually. + +**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted. + +**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`. + +**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests. + +--- + +## Current Models (cached: 2026-02-17) + +| Model | Model ID | Context | Input $/1M | Output $/1M | +| ----------------- | ------------------- | -------------- | ---------- | ----------- | +| Claude Opus 4.6 | `claude-opus-4-6` | 200K (1M beta) | $5.00 | $25.00 | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00 | $15.00 | +| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 | + +**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. + +**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself. + +A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that. + +**Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples. + +--- + +## Thinking & Effort (Quick Reference) + +**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` and do NOT switch to an older model.** + +**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — `medium` is often a favorable balance; use `max` when correctness matters more than cost; use `low` for subagents or simple tasks. + +**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead. + +**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.6 with adaptive thinking instead. + +--- + +## Compaction (Quick Reference) + +**Beta, Opus 4.6 and Sonnet 4.6.** For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`. + +**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state. + +See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`. + +--- + +## Prompt Caching (Quick Reference) + +**Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint. + +**Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache. + +**Verify with `usage.cache_read_input_tokens`** — if it's zero across repeated requests, a silent invalidator is at work (`datetime.now()` in system prompt, unsorted JSON, varying tool set). + +For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read `shared/prompt-caching.md`. Language-specific syntax: `{lang}/claude-api/README.md` (Prompt Caching section). + +--- + +## Managed Agents (Beta) + +**Managed Agents** is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (`POST /v1/agents`), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back. + +**Managed Agents is first-party only.** It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. For agents on third-party providers, use Claude API + tool use. + +**Mandatory flow:** Agent (once) → Session (every run). `model`/`system`/`tools` live on the agent, never the session. See `shared/managed-agents-overview.md` for the full reading guide, beta headers, and pitfalls. + +**Beta headers:** `managed-agents-2026-04-01` — the SDK sets this automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills API uses `skills-2025-10-02` and Files API uses `files-api-2025-04-14`, but you don't need to explicitly pass those in for endpoints other than `/v1/skills` and `/v1/files`. + +**Subcommands** — invoke directly with `/claude-api `: + +| Subcommand | Action | +|---|---| +| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: mental model → know-or-explore branch → template config → session setup → emit code. Do not summarize — run the interview. | + +**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use raw HTTP from `curl/managed-agents.md` as a reference. + +**When the user wants to set up a Managed Agent from scratch** (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read `shared/managed-agents-onboarding.md` and run its interview — same flow as the `managed-agents-onboard` subcommand. + +**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc. + +--- + +## Reading Guide + +After detecting the language, read the relevant files based on what the user needs: + +### Quick Task Reference + +**Single text classification/summarization/extraction/Q&A:** +→ Read only `{lang}/claude-api/README.md` + +**Chat UI or real-time response display:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md` + +**Long-running conversations (may exceed context window):** +→ Read `{lang}/claude-api/README.md` — see Compaction section + +**Prompt caching / optimize caching / "why is my cache hit rate low":** +→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section) + +**Function calling / tool use / agents:** +→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` + +**Agent design (tool surface, context management, caching strategy):** +→ Read `shared/agent-design.md` + +**Batch processing (non-latency-sensitive):** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md` + +**File uploads across multiple requests:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md` + +**Managed Agents (server-managed stateful agents with workspace):** +→ Read `shared/managed-agents-overview.md` + the rest of the `shared/managed-agents-*.md` files. For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently support Managed Agents — use raw HTTP from `curl/managed-agents.md` as a reference. + +### Claude API (Full File Reference) + +Read the **language-specific Claude API folder** (`{language}/claude-api/`): + +1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling. +2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations. +3. **`shared/agent-design.md`** — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles. +4. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs). +5. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally. +6. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost. +7. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading. +8. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache. +9. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling. +10. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation. + +> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed. + +> **Note:** For the Managed Agents file reference, see the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs. + +--- + +## When to Use WebFetch + +Use WebFetch to get the latest documentation when: + +- User asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered here + +Live documentation URLs are in `shared/live-sources.md`. + +## Common Pitfalls + +- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating. +- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong. +- **Opus 4.6 prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. +- **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, or deliberately short outputs. +- **128K output tokens:** Opus 4.6 supports up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`. +- **Tool call JSON parsing (Opus 4.6):** Opus 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input. +- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific. +- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces. +- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety. +- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text. diff --git a/junie/versions/2206.3/skills/claude-api/csharp/claude-api.md b/junie/versions/2206.3/skills/claude-api/csharp/claude-api.md new file mode 100644 index 0000000..e0e790a --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/csharp/claude-api.md @@ -0,0 +1,402 @@ +# Claude API — C# + +> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation. + +## Installation + +```bash +dotnet add package Anthropic +``` + +## Client Initialization + +```csharp +using Anthropic; + +// Default (uses ANTHROPIC_API_KEY env var) +AnthropicClient client = new(); + +// Explicit API key (use environment variables — never hardcode keys) +AnthropicClient client = new() { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") +}; +``` + +--- + +## Basic Message Request + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }] +}; +var response = await client.Messages.Create(parameters); + +// ContentBlock is a union wrapper. .Value unwraps to the variant object, +// then OfType filters to the type you want. Or use the TryPick* idiom +// shown in the Thinking section below. +foreach (var text in response.Content.Select(b => b.Value).OfType()) +{ + Console.WriteLine(text.Text); +} +``` + +--- + +## Streaming + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 64000, + Messages = [new() { Role = Role.User, Content = "Write a haiku" }] +}; + +await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters)) +{ + if (streamEvent.TryPickContentBlockDelta(out var delta) && + delta.Delta.TryPickText(out var text)) + { + Console.Write(text.Text); + } +} +``` + +**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`. + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```csharp +using Anthropic.Models.Messages; + +var response = await client.Messages.Create(new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + // ThinkingConfigParam? implicitly converts from the concrete variant classes — + // no wrapper needed. + Thinking = new ThinkingConfigAdaptive(), + Messages = + [ + new() { Role = Role.User, Content = "Solve: 27 * 453" }, + ], +}); + +// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union. +foreach (var block in response.Content) +{ + if (block.TryPickThinking(out ThinkingBlock? t)) + { + Console.WriteLine($"[thinking] {t.Thinking}"); + } + else if (block.TryPickText(out TextBlock? text)) + { + Console.WriteLine(text.Text); + } +} +``` + +> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +Alternative to `TryPick*`: `.Select(b => b.Value).OfType()` (same LINQ pattern as the Basic Message example). + +--- + +## Tool Use + +### Defining a tool + +`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`. + +```csharp +using System.Text.Json; +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeSonnet4_6, + MaxTokens = 16000, + Tools = [ + new Tool { + Name = "get_weather", + Description = "Get the current weather in a given location", + InputSchema = new() { + Properties = new Dictionary { + ["location"] = JsonSerializer.SerializeToElement( + new { type = "string", description = "City name" }), + }, + Required = ["location"], + }, + }, + ], + Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }], +}; +``` + +Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion). + +See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. +### Converting response content to the follow-up assistant message + +When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path). + +```csharp +using Anthropic.Models.Messages; + +Message response = await client.Messages.Create(parameters); + +// No .ToParam() — reconstruct per variant. Implicit conversions from each +// *Param type to ContentBlockParam mean no explicit wrapper. +List assistantContent = []; +List toolResults = []; +foreach (ContentBlock block in response.Content) +{ + if (block.TryPickText(out TextBlock? text)) + { + assistantContent.Add(new TextBlockParam { Text = text.Text }); + } + else if (block.TryPickThinking(out ThinkingBlock? thinking)) + { + // Signature MUST be preserved — the API rejects tampering + assistantContent.Add(new ThinkingBlockParam + { + Thinking = thinking.Thinking, + Signature = thinking.Signature, + }); + } + else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted)) + { + assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data }); + } + else if (block.TryPickToolUse(out ToolUseBlock? toolUse)) + { + // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it + assistantContent.Add(new ToolUseBlockParam + { + ID = toolUse.ID, + Name = toolUse.Name, + Input = toolUse.Input, + }); + // Execute the tool; collect ONE result per tool_use block — the API + // rejects the follow-up if any tool_use ID lacks a matching tool_result. + string result = ExecuteYourTool(toolUse.Name, toolUse.Input); + toolResults.Add(new ToolResultBlockParam + { + ToolUseID = toolUse.ID, + Content = result, + }); + } +} + +// Follow-up: prior messages + assistant echo + user tool_result(s) +List followUpMessages = +[ + .. parameters.Messages, + new() { Role = Role.Assistant, Content = assistantContent }, + new() { Role = Role.User, Content = toolResults }, +]; +``` + +`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts. + +--- + +## Context Editing / Compaction (Beta) + +**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`: + +```csharp +using Anthropic.Models.Beta.Messages; +using NonBeta = Anthropic.Models.Messages; // only if you also need non-beta types +// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed) +``` + + +`BetaMessage.Content` is `IReadOnlyList` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block: + +```csharp +using Anthropic.Models.Beta.Messages; + +var betaParams = new MessageCreateParams // no Beta prefix — one of only 2 unprefixed +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Betas = ["compact-2026-01-12"], + ContextManagement = new BetaContextManagementConfig + { + Edits = [new BetaCompact20260112Edit()], + }, + Messages = messages, +}; +BetaMessage resp = await client.Beta.Messages.Create(betaParams); + +foreach (BetaContentBlock block in resp.Content) +{ + if (block.TryPickCompaction(out BetaCompactionBlock? compaction)) + { + // Content is nullable — compaction can fail server-side + Console.WriteLine($"compaction summary: {compaction.Content}"); + } +} + +// Context-edit metadata lives on a separate nullable field +if (resp.ContextManagement is { } ctx) +{ + foreach (var edit in ctx.AppliedEdits) + Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens"); +} + +// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list +// union). It implicit-converts from List, NOT from the +// response's IReadOnlyList. Convert each block: +List paramBlocks = []; +foreach (var b in resp.Content) +{ + if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text }); + else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content }); + // ... other variants as needed +} +messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks }); +``` + +All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`. + +**`BetaToolUseBlock.Input` is `IReadOnlyDictionary`** — index by key then call the `JsonElement` extractor: + +```csharp +if (block.TryPickToolUse(out BetaToolUseBlock? tu)) +{ + int a = tu.Input["a"].GetInt32(); + string s = tu.Input["name"].GetString()!; +} +``` + +--- + +## Effort Parameter + +Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum` has an implicit conversion from the enum, so assign `Effort.High` directly. + +```csharp +OutputConfig = new OutputConfig { Effort = Effort.High }, +``` + +Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control. + +--- + +## Prompt Caching + +`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```csharp +System = new List { + new() { + Text = longSystemPrompt, + CacheControl = new CacheControlEphemeral(), // auto-sets Type = "ephemeral" + }, +}, +``` + +Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`. + +Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`. + +--- + +## Token Counting + +```csharp +MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams { + Model = Model.ClaudeOpus4_6, + Messages = [new() { Role = Role.User, Content = "Hello" }], +}); +long tokens = result.InputTokens; +``` + +`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters. + +--- + +## Structured Output + +```csharp +OutputConfig = new OutputConfig { + Format = new JsonOutputFormat { + Schema = new Dictionary { + ["type"] = JsonSerializer.SerializeToElement("object"), + ["properties"] = JsonSerializer.SerializeToElement( + new { name = new { type = "string" } }), + ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }), + }, + }, +}, +``` + +`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`. + +```csharp +new MessageParam { + Role = Role.User, + Content = new List { + new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } }, + new TextBlockParam { Text = "Summarize this PDF" }, + }, +} +``` + +--- + +## Server-Side Tools + +Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`. + +```csharp +Tools = [ + new WebSearchTool20260209(), + new ToolBash20250124(), + new ToolTextEditor20250728(), + new CodeExecutionTool20260120(), +], +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`. + +--- + +## Files API (Beta) + +Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`. + +```csharp +using Anthropic.Models.Beta.Files; +using Anthropic.Models.Beta.Messages; + +FileMetadata meta = await client.Beta.Files.Upload( + new FileUploadParams { File = File.OpenRead("doc.pdf") }); + +// Referencing the uploaded file requires Beta message types: +new BetaRequestDocumentBlock { + Source = new BetaFileDocumentSource { FileID = meta.ID }, +} +``` + +The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`. diff --git a/junie/versions/2206.3/skills/claude-api/curl/examples.md b/junie/versions/2206.3/skills/claude-api/curl/examples.md new file mode 100644 index 0000000..e08b443 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/curl/examples.md @@ -0,0 +1,216 @@ +# Claude API — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +--- + +## Basic Message Request + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "messages": [ + {"role": "user", "content": "What is the capital of France?"} + ] + }' +``` + +### Parsing the response + +Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` — +JSON strings can contain any character and regex parsing will break on quotes, +escapes, or multi-line content. + +```bash +# Capture the response, then extract fields +response=$(curl -s https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{"model":"claude-opus-4-6","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') + +# Print the first text block (-r strips the JSON quotes) +echo "$response" | jq -r '.content[0].text' + +# Read usage fields +input_tokens=$(echo "$response" | jq -r '.usage.input_tokens') +output_tokens=$(echo "$response" | jq -r '.usage.output_tokens') + +# Read stop reason (for tool-use loops) +stop_reason=$(echo "$response" | jq -r '.stop_reason') + +# Extract all text blocks (content is an array; filter to type=="text") +echo "$response" | jq -r '.content[] | select(.type == "text") | .text' +``` + + +--- + +## Streaming (SSE) + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 64000, + "stream": true, + "messages": [{"role": "user", "content": "Write a haiku"}] + }' +``` + +The response is a stream of Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` + +--- + +## Tool Use + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [{"role": "user", "content": "What is the weather in Paris?"}] + }' +``` + +When Claude responds with a `tool_use` block, send the result back: + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": [ + {"type": "text", "text": "Let me check the weather."}, + {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}} + ]}, + {"role": "user", "content": [ + {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"} + ]} + ] + }' +``` + +--- + +## Prompt Caching + +Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist. + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} + ], + "messages": [{"role": "user", "content": "Summarize the key points"}] + }' +``` + +For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). + +```bash +# Opus 4.6: adaptive thinking (recommended) +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "thinking": { + "type": "adaptive" + }, + "output_config": { + "effort": "high" + }, + "messages": [{"role": "user", "content": "Solve this step by step..."}] + }' +``` + +--- + +## Required Headers + +| Header | Value | Description | +| ------------------- | ------------------ | -------------------------- | +| `Content-Type` | `application/json` | Required | +| `x-api-key` | Your API key | Authentication | +| `anthropic-version` | `2023-06-01` | API version | +| `anthropic-beta` | Beta feature IDs | Required for beta features | diff --git a/junie/versions/2206.3/skills/claude-api/curl/managed-agents.md b/junie/versions/2206.3/skills/claude-api/curl/managed-agents.md new file mode 100644 index 0000000..3a684cf --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/curl/managed-agents.md @@ -0,0 +1,333 @@ +# Managed Agents — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working without an SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" + +# Common headers +HEADERS=( + -H "Content-Type: application/json" + -H "x-api-key: $ANTHROPIC_API_KEY" + -H "anthropic-version: 2023-06-01" + -H "anthropic-beta: managed-agents-2026-04-01" +) +``` + +--- + +## Create an Environment + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "my-dev-env", + "config": { + "type": "cloud", + "networking": { "type": "unrestricted" } + } + }' +``` + +### With restricted networking + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "restricted-env", + "config": { + "type": "cloud", + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } + } + }' +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Under `managed-agents-2026-04-01`, `model`/`system`/`tools` are top-level fields on `POST /v1/agents`, not on the session. Always create the agent first — the session only takes `"agent": {"type": "agent", "id": "..."}`. + +### Minimal + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Coding Assistant", + "model": "claude-opus-4-6", + "tools": [{ "type": "agent_toolset_20260401" }] + }' +# → { "id": "agent_abc123", ... } + +# 2. Start a session +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123" + }' +``` + +### With system prompt, custom tools, and GitHub repo + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Code Reviewer", + "model": "claude-opus-4-6", + "system": "You are a senior code reviewer. Be thorough and constructive.", + "tools": [ + { "type": "agent_toolset_20260401" }, + { + "type": "custom", + "name": "run_linter", + "description": "Run the project linter on a file", + "input_schema": { + "type": "object", + "properties": { + "file_path": { "type": "string", "description": "Path to lint" } + }, + "required": ["file_path"] + } + } + ] + }' + +# 2. Start a session with the repo mounted +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123", + "title": "Code review session", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": "ghp_...", + "branch": "feature-branch" + } + ] + }' +``` + +--- + +## Send a User Message + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.message", + "content": [{ "type": "text", "text": "Review the auth module for security issues" }] + } + ] + }' +``` + +--- + +## Stream Events (SSE) + +```bash +curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + "${HEADERS[@]}" +``` + +Response format: + +``` +event: session.status_running +data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."} + +event: agent.message +data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."} + +event: session.status_idle +data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."} +``` + +--- + +## Poll Events + +```bash +# Get all events +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" + +# Paginated — get next page of events +curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \ + "${HEADERS[@]}" +``` + +--- + +## Provide Custom Tool Result + +When the agent calls a custom tool, send the result back: + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "No linting errors found." }] + } + ] + }' +``` + +--- + +## Interrupt a Running Session + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "interrupt" + } + ] + }' +``` + +--- + +## Get Session Details + +```bash +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## List Sessions + +```bash +curl https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" +``` + +--- + +## Delete a Session + +```bash +curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## Upload a File + +```bash +curl -X POST https://api.anthropic.com/v1/files \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: files-api-2025-04-14" \ + -F "file=@path/to/file.txt" \ + -F "purpose=agent" +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```bash +# List files associated with a session +curl "https://api.anthropic.com/v1/files?scope=$SESSION_ID" \ + "${HEADERS[@]}" + +# Download a specific file +curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ + "${HEADERS[@]}" \ + -o downloaded_file.txt +``` + +--- + +## List Agents + +```bash +curl https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" +``` + +--- + +## MCP Server Integration + +```bash +# 1. Agent declares MCP server (no auth here — auth goes in a vault) +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "MCP Agent", + "model": "claude-opus-4-6", + "mcp_servers": [ + { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" } + ], + "tools": [ + { "type": "agent_toolset_20260401" }, + { "type": "mcp_toolset", "mcp_server_name": "my-tools" } + ] + }' + +# 2. Session attaches vault containing credentials for that MCP server URL +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] + }' +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Tool Configuration + +```bash +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Restricted Agent", + "model": "claude-opus-4-6", + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] + }' +``` diff --git a/junie/versions/2206.3/skills/claude-api/go/claude-api.md b/junie/versions/2206.3/skills/claude-api/go/claude-api.md new file mode 100644 index 0000000..019b80f --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/go/claude-api.md @@ -0,0 +1,421 @@ +# Claude API — Go + +> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) +``` + +--- + +## Basic Message Request + +```go +response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + }, +}) +if err != nil { + log.Fatal(err) +} +for _, block := range response.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + } +} +``` + +--- + +## Streaming + +```go +stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 64000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")), + }, +}) + +for stream.Next() { + event := stream.Current() + switch eventVariant := event.AsAny().(type) { + case anthropic.ContentBlockDeltaEvent: + switch deltaVariant := eventVariant.Delta.AsAny().(type) { + case anthropic.TextDelta: + fmt.Print(deltaVariant.Text) + } + } +} +if err := stream.Err(); err != nil { + log.Fatal(err) +} +``` + +**Accumulating the final message** (there is no `GetFinalMessage()` on the stream): + +```go +stream := client.Messages.NewStreaming(ctx, params) +message := anthropic.Message{} +for stream.Next() { + message.Accumulate(stream.Current()) +} +if err := stream.Err(); err != nil { log.Fatal(err) } +// message.Content now has the complete response +``` + + +--- + +## Tool Use + +### Tool Runner (Beta — Recommended) + +**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package. + +```go +import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/toolrunner" +) + +// Define tool input with jsonschema tags for automatic schema generation +type GetWeatherInput struct { + City string `json:"city" jsonschema:"required,description=The city name"` +} + +// Create a tool with automatic schema generation from struct tags +weatherTool, err := toolrunner.NewBetaToolFromJSONSchema( + "get_weather", + "Get current weather for a city", + func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) { + return anthropic.BetaToolResultBlockParamContentUnion{ + OfText: &anthropic.BetaTextBlockParam{ + Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City), + }, + }, nil + }, +) +if err != nil { + log.Fatal(err) +} + +// Create a tool runner that handles the conversation loop automatically +runner := client.Beta.Messages.NewToolRunner( + []anthropic.BetaTool{weatherTool}, + anthropic.BetaToolRunnerParams{ + BetaMessageNewParams: anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.BetaMessageParam{ + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")), + }, + }, + MaxIterations: 5, + }, +) + +// Run until Claude produces a final response +message, err := runner.RunToCompletion(context.Background()) +if err != nil { + log.Fatal(err) +} + +// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion. +// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock, +// not TextBlock): +for _, block := range message.Content { + switch block := block.AsAny().(type) { + case anthropic.BetaTextBlock: + fmt.Println(block.Text) + } +} +``` + +**Key features of the Go tool runner:** + +- Automatic schema generation from Go structs via `jsonschema` tags +- `RunToCompletion()` for simple one-shot usage +- `All()` iterator for processing each message in the conversation +- `NextMessage()` for step-by-step iteration +- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()` + +### Manual Loop + +For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls. + +Derived from `anthropic-sdk-go/examples/tools/main.go`. + +```go +package main + +import ( + "context" + "encoding/json" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" +) + +func main() { + client := anthropic.NewClient() + + // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed. + addTool := anthropic.ToolParam{ + Name: "add", + Description: anthropic.String("Add two integers"), + InputSchema: anthropic.ToolInputSchemaParam{ + Properties: map[string]any{ + "a": map[string]any{"type": "integer"}, + "b": map[string]any{"type": "integer"}, + }, + }, + } + // ToolParam must be wrapped in ToolUnionParam for the Tools slice + tools := []anthropic.ToolUnionParam{{OfTool: &addTool}} + + messages := []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")), + } + + for { + resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Messages: messages, + Tools: tools, + }) + if err != nil { + log.Fatal(err) + } + + // 2. Append the assistant response to history BEFORE processing tool calls. + // resp.ToParam() converts Message → MessageParam in one call. + messages = append(messages, resp.ToParam()) + + // 3. Walk content blocks. ContentBlockUnion is a flattened struct; + // use block.AsAny().(type) to switch on the actual variant. + toolResults := []anthropic.ContentBlockParamUnion{} + for _, block := range resp.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + case anthropic.ToolUseBlock: + // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the + // raw JSON — block.Input is json.RawMessage, not the parsed value. + var in struct { + A int `json:"a"` + B int `json:"b"` + } + if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil { + log.Fatal(err) + } + result := fmt.Sprintf("%d", in.A+in.B) + // 5. NewToolResultBlock(toolUseID, content, isError) builds the + // ContentBlockParamUnion for you. block.ID is the tool_use_id. + toolResults = append(toolResults, + anthropic.NewToolResultBlock(block.ID, result, false)) + } + } + + // 6. Exit when Claude stops asking for tools + if resp.StopReason != anthropic.StopReasonToolUse { + break + } + + // 7. Tool results go in a user message (variadic: all results in one turn) + messages = append(messages, anthropic.NewUserMessage(toolResults...)) + } +} +``` + +**Key API surface:** + +| Symbol | Purpose | +|---|---| +| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history | +| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants | +| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) | +| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block | +| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn | +| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination | +| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` | + +--- + +## Thinking + +Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`. + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control. + +Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `NewThinkingConfigAdaptiveParam`). + +```go +// There is no ThinkingConfigParamOfAdaptive helper — construct the union +// struct-literal directly and take the address of the variant. +adaptive := anthropic.NewThinkingConfigAdaptiveParam() +params := anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive}, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")), + }, +} + +resp, err := client.Messages.New(context.Background(), params) +if err != nil { + log.Fatal(err) +} + +// ThinkingBlock(s) precede TextBlock in content +for _, block := range resp.Content { + switch b := block.AsAny().(type) { + case anthropic.ThinkingBlock: + fmt.Println("[thinking]", b.Thinking) + case anthropic.TextBlock: + fmt.Println(b.Text) + } +} +``` + +> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. + +--- + +## Prompt Caching + +`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```go +System: []anthropic.TextBlockParam{{ + Text: longSystemPrompt, + CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL +}}, +``` + +For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block. + +Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`. + +--- + +## Server-Side Tools + +Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field. + +```go +Tools: []anthropic.ToolUnionParam{ + {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}}, + {OfBashTool20250124: &anthropic.ToolBash20250124Param{}}, + {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}}, + {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}}, +}, +``` + +Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. + +--- + +## PDF / Document Input + +`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set. + +```go +b64 := base64.StdEncoding.EncodeToString(pdfBytes) + +msg := anthropic.NewUserMessage( + anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}), + anthropic.NewTextBlock("Summarize this document"), +) +``` + +Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`. + +--- + +## Files API (Beta) + +Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding. + +```go +f, _ := os.Open("./upload_me.txt") +defer f.Close() + +meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: anthropic.File(f, "upload_me.txt", "text/plain"), + Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14}, +}) +// meta.ID is the file_id to reference in subsequent message requests +``` + +Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`. + +--- + +## Context Editing / Compaction (Beta) + +Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip. + +```go +params := anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, // also supported: ModelClaudeSonnet4_6 + MaxTokens: 16000, + Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, + ContextManagement: anthropic.BetaContextManagementConfigParam{ + Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ + {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, + }, + }, + Messages: []anthropic.BetaMessageParam{ /* ... */ }, +} + +resp, err := client.Beta.Messages.New(ctx, params) +if err != nil { + log.Fatal(err) +} + +// Round-trip: append response to history via .ToParam() +params.Messages = append(params.Messages, resp.ToParam()) + +// Read compaction blocks from the response +for _, block := range resp.Content { + if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok { + fmt.Println("compaction summary:", c.Content) + } +} +``` + +Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`. diff --git a/junie/versions/2206.3/skills/claude-api/go/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/go/managed-agents/README.md new file mode 100644 index 0000000..e7b855f --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/go/managed-agents/README.md @@ -0,0 +1,561 @@ +# Managed Agents — Go + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Go. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Go SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "context" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) + +ctx := context.Background() +``` + +--- + +## Create an Environment + +```go +environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ + Name: "my-dev-env", + Config: anthropic.BetaCloudConfigParams{ + Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ + OfUnrestricted: &anthropic.UnrestrictedNetworkParam{}, + }, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(environment.ID) // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `Model`/`System`/`Tools` live on the agent object, not the session. Always start with `Beta.Agents.New()` — the session only takes `Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}` (or the typed `OfBetaManagedAgentsAgents` variant when you need a specific version). + +### Minimal + +```go +// 1. Create the agent (reusable, versioned) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "Coding Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + System: anthropic.String("You are a helpful coding assistant."), + Tools: []anthropic.BetaAgentNewParamsToolUnion{{ + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }}, +}) +if err != nil { + panic(err) +} + +// 2. Start a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + Title: anthropic.String("Quickstart session"), +}) +if err != nil { + panic(err) +} +fmt.Printf("Session ID: %s, status: %s\n", session.ID, session.Status) +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```go +updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ + Version: agent.Version, + System: anthropic.String("You are a helpful coding agent. Always write tests."), +}) +if err != nil { + panic(err) +} +fmt.Printf("New version: %d\n", updatedAgent.Version) + +// List all versions +iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{}) +for iter.Next() { + version := iter.Current() + fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339)) +} +if err := iter.Err(); err != nil { + panic(err) +} + +// Archive the agent +_, err = client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## Send a User Message + +```go +_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Review the auth module", + }, + }}, + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```go +// Open the stream first, then send the user message +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Summarize the repo README", + }, + }}, + }, + }}, +}); err != nil { + panic(err) +} + +events: +for stream.Next() { + switch event := stream.Current().AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsAgentToolUseEvent: + fmt.Printf("\n[Using tool: %s]\n", event.Name) + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break events + case anthropic.BetaManagedAgentsSessionErrorEvent: + fmt.Printf("\n[Error: %s]\n", event.Error.Message) + break events + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```go +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +// Stream is open and buffering. List history before tailing live. +seenEventIDs := map[string]struct{}{} +history := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for history.Next() { + seenEventIDs[history.Current().ID] = struct{}{} +} +if err := history.Err(); err != nil { + panic(err) +} + +// Tail live events, skipping anything already seen +tail: +for stream.Next() { + event := stream.Current() + if _, seen := seenEventIDs[event.ID]; seen { + continue + } + seenEventIDs[event.ID] = struct{}{} + switch event := event.AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break tail + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Go managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `github.com/anthropics/anthropic-sdk-go` repository for the corresponding Go params types. + +--- + +## Poll Events + +```go +// Auto-paginating iterator +iter := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for iter.Next() { + event := iter.Current() + fmt.Printf("%s: %s\n", event.Type, event.ID) +} +if err := iter.Err(); err != nil { + panic(err) +} +``` + +--- + +## Upload a File + +```go +csvFile, err := os.Open("data.csv") +if err != nil { + panic(err) +} +defer csvFile.Close() + +file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: csvFile, +}) +if err != nil { + panic(err) +} +fmt.Printf("File ID: %s\n", file.ID) + +// Mount in a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String(agent.ID), + }, + EnvironmentID: environment.ID, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{{ + OfFile: &anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + MountPath: anthropic.String("/workspace/data.csv"), + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +### Add and Manage Resources on an Existing Session + +```go +// Attach an additional file to an open session +resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(resource.ID) // "sesrsc_01ABC..." + +// List resources on the session +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +for _, entry := range listed.Data { + fmt.Println(entry.ID, entry.Type) +} + +// Detach a resource +if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{ + SessionID: session.ID, +}); err != nil { + panic(err) +} +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Go in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `github.com/anthropics/anthropic-sdk-go` repository for the `Beta.Files.List` and `Beta.Files.Download` Go params types. + +--- + +## Session Management + +```go +// List environments +environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{}) +if err != nil { + panic(err) +} + +// Retrieve a specific environment +env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{}) +if err != nil { + panic(err) +} + +// Archive an environment (read-only, existing sessions continue) +_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{}) +if err != nil { + panic(err) +} + +// Delete an environment (only if no sessions reference it) +_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{}) +if err != nil { + panic(err) +} + +// Delete a session +_, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## MCP Server Integration + +```go +// Agent declares MCP server (no auth here — auth goes in a vault) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "GitHub Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + MCPServers: []anthropic.BetaManagedAgentsUrlmcpServerParams{{ + Type: anthropic.BetaManagedAgentsUrlmcpServerParamsTypeURL, + Name: "github", + URL: "https://api.githubcopilot.com/mcp/", + }}, + Tools: []anthropic.BetaAgentNewParamsToolUnion{ + { + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }, + { + OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ + Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, + MCPServerName: "github", + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Session attaches vault(s) containing credentials for those MCP server URLs +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, +}) +if err != nil { + panic(err) +} +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```go +// Create a vault +vault, err := client.Beta.Vaults.New(ctx, anthropic.BetaVaultNewParams{ + DisplayName: "Alice", + Metadata: map[string]string{"external_user_id": "usr_abc123"}, +}) +if err != nil { + panic(err) +} + +// Add an OAuth credential +credential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{ + DisplayName: anthropic.String("Alice's Slack"), + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthCreateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth, + MCPServerURL: "https://mcp.slack.com/mcp", + AccessToken: "xoxp-...", + ExpiresAt: anthropic.Time(time.Date(2026, time.April, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshParams{ + TokenEndpoint: "https://slack.com/api/oauth.v2.access", + ClientID: "1234567890.0987654321", + Scope: anthropic.String("channels:read chat:write"), + RefreshToken: "xoxe-1-...", + TokenEndpointAuth: anthropic.BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnion{ + OfClientSecretPost: &anthropic.BetaManagedAgentsTokenEndpointAuthPostParam{ + Type: anthropic.BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost, + ClientSecret: "abc123...", + }, + }, + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Rotate the credential (e.g., after a token refresh) +_, err = client.Beta.Vaults.Credentials.Update(ctx, credential.ID, anthropic.BetaVaultCredentialUpdateParams{ + VaultID: vault.ID, + Auth: anthropic.BetaVaultCredentialUpdateParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthUpdateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth, + AccessToken: anthropic.String("xoxp-new-..."), + ExpiresAt: anthropic.Time(time.Date(2026, time.May, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshUpdateParams{ + RefreshToken: anthropic.String("xoxe-1-new-..."), + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Archive a vault +_, err = client.Beta.Vaults.Archive(ctx, vault.ID, anthropic.BetaVaultArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```go +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/repo", + MountPath: anthropic.String("/workspace/repo"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + }, +}) +if err != nil { + panic(err) +} +``` + +Multiple repositories on the same session: + +```go +resources := []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/frontend", + MountPath: anthropic.String("/workspace/frontend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/backend", + MountPath: anthropic.String("/workspace/backend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, +} +``` + +Rotating a repository's authorization token: + +```go +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +repoResourceID := listed.Data[0].ID + +_, err = client.Beta.Sessions.Resources.Update(ctx, repoResourceID, anthropic.BetaSessionResourceUpdateParams{ + SessionID: session.ID, + AuthorizationToken: "ghp_your_new_github_token", +}) +if err != nil { + panic(err) +} +``` diff --git a/junie/versions/2206.3/skills/claude-api/java/claude-api.md b/junie/versions/2206.3/skills/claude-api/java/claude-api.md new file mode 100644 index 0000000..22f872e --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/java/claude-api.md @@ -0,0 +1,432 @@ +# Claude API — Java + +> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java. + +## Installation + +Maven: + +```xml + + com.anthropic + anthropic-java + 2.17.0 + +``` + +Gradle: + +```groovy +implementation("com.anthropic:anthropic-java:2.17.0") +``` + +## Client Initialization + +```java +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (reads ANTHROPIC_API_KEY from environment) +AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + +// Explicit API key +AnthropicClient client = AnthropicOkHttpClient.builder() + .apiKey("your-api-key") + .build(); +``` + +--- + +## Basic Message Request + +```java +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Message; +import com.anthropic.models.messages.Model; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addUserMessage("What is the capital of France?") + .build(); + +Message response = client.messages().create(params); +response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> System.out.println(textBlock.text())); +``` + +--- + +## Streaming + +```java +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.messages.RawMessageStreamEvent; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(64000L) + .addUserMessage("Write a haiku") + .build(); + +try (StreamResponse streamResponse = client.messages().createStreaming(params)) { + streamResponse.stream() + .flatMap(event -> event.contentBlockDelta().stream()) + .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) + .forEach(textDelta -> System.out.print(textDelta.text())); +} +``` + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping. + +```java +import com.anthropic.models.messages.ContentBlock; +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Model; +import com.anthropic.models.messages.ThinkingConfigAdaptive; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .addUserMessage("Solve this step by step: 27 * 453") + .build(); + +for (ContentBlock block : client.messages().create(params).content()) { + block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking())); + block.text().ifPresent(t -> System.out.println(t.text())); +} +``` + +> **Deprecated:** `ThinkingConfigEnabled.builder().budgetTokens(N)` (and the `.enabledThinking(N)` shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant). + +--- + +## Tool Use (Beta) + +The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier` for automatic execution via `BetaToolRunner`. + +### Tool Runner (automatic loop) + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.helpers.BetaToolRunner; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; +import java.util.function.Supplier; + +@JsonClassDescription("Get the weather in a given location") +static class GetWeather implements Supplier { + @JsonPropertyDescription("The city and state, e.g. San Francisco, CA") + public String location; + + @Override + public String get() { + return "The weather in " + location + " is sunny and 72°F"; + } +} + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(16000L) + .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13") + .addTool(GetWeather.class) + .addUserMessage("What's the weather in San Francisco?") + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +### Memory Tool + +The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically. + +```java +import com.anthropic.helpers.BetaMemoryToolHandler; +import com.anthropic.helpers.BetaToolRunner; +import com.anthropic.models.beta.messages.BetaMemoryTool20250818; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.ToolRunnerCreateParams; + +// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem) +BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot); + +MessageCreateParams createParams = MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(4096L) + .addTool(BetaMemoryTool20250818.builder().build()) + .addUserMessage("Remember that my favorite color is blue") + .build(); + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + ToolRunnerCreateParams.builder() + .betaMemoryToolHandler(memoryHandler) + .initialMessageParams(createParams) + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +See the [shared memory tool concepts](../shared/tool-use-concepts.md) for more details on the memory tool. + +### Non-Beta Tool Declaration (manual JSON schema) + +`Tool.InputSchema.Properties` is a freeform `Map` wrapper — build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically. + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.messages.Tool; + +Tool tool = Tool.builder() + .name("get_weather") + .description("Get the current weather in a given location") + .inputSchema(Tool.InputSchema.builder() + .properties(Tool.InputSchema.Properties.builder() + .putAdditionalProperty("location", JsonValue.from(Map.of("type", "string"))) + .build()) + .required(List.of("location")) + .build()) + .build(); + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .addTool(tool) + .addUserMessage("Weather in Paris?") + .build(); +``` + +For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../shared/tool-use-concepts.md). + +### Building `MessageParam` with Content Blocks (Tool Result Round-Trip) + +`MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List)` alias — there is NO separate `MessageParamContent` class with a static `ofBlockParams`: + +```java +import com.anthropic.models.messages.MessageParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.ToolResultBlockParam; + +List results = List.of( + ContentBlockParam.ofToolResult(ToolResultBlockParam.builder() + .toolUseId(toolUseBlock.id()) + .content(yourResultString) + .build()) +); + +MessageParam toolResultMsg = MessageParam.builder() + .role(MessageParam.Role.USER) + .contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...) + .build(); +``` + +--- + +## Effort Parameter + +Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`. + +```java +import com.anthropic.models.messages.OutputConfig; + +.outputConfig(OutputConfig.builder() + .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX + .build()) +``` + +Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control. + +--- + +## Prompt Caching + +System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```java +import com.anthropic.models.messages.TextBlockParam; +import com.anthropic.models.messages.CacheControlEphemeral; + +.systemOfTextBlockParams(List.of( + TextBlockParam.builder() + .text(longSystemPrompt) + .cacheControl(CacheControlEphemeral.builder() + .ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M + .build()) + .build())) +``` + +There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`. + +Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`. + +--- + +## Token Counting + +```java +import com.anthropic.models.messages.MessageCountTokensParams; + +long tokens = client.messages().countTokens( + MessageCountTokensParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .addUserMessage("Hello") + .build() +).inputTokens(); +``` + +--- + +## Structured Output + +The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing. + +```java +import com.anthropic.models.messages.StructuredMessageCreateParams; + +record Book(String title, String author) {} +record BookList(List books) {} + +StructuredMessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .outputConfig(BookList.class) // returns a typed builder + .addUserMessage("List 3 classic novels") + .build(); + +client.messages().create(params).content().stream() + .flatMap(cb -> cb.text().stream()) + .forEach(typed -> { + // typed.text() returns BookList, not String + for (Book b : typed.text().books()) System.out.println(b.title()); + }); +``` + +Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`. + +```java +import com.anthropic.models.messages.DocumentBlockParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.TextBlockParam; + +DocumentBlockParam doc = DocumentBlockParam.builder() + .base64Source(base64String) // or .urlSource("https://...") or .textSource("...") + .title("My Document") // optional + .build(); + +.addUserMessageOfBlockParams(List.of( + ContentBlockParam.ofDocument(doc), + ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build()))) +``` + +--- + +## Server-Side Tools + +Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for every type — no manual `ToolUnion` wrapping. + +```java +import com.anthropic.models.messages.WebSearchTool20260209; +import com.anthropic.models.messages.ToolBash20250124; +import com.anthropic.models.messages.ToolTextEditor20250728; +import com.anthropic.models.messages.CodeExecutionTool20260120; + +.addTool(WebSearchTool20260209.builder() + .maxUses(5L) // optional + .allowedDomains(List.of("example.com")) // optional + .build()) +.addTool(ToolBash20250124.builder().build()) +.addTool(ToolTextEditor20250728.builder().build()) +.addTool(CodeExecutionTool20260120.builder().build()) +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. + +### Beta namespace (MCP, compaction) + +For beta-only features use `com.anthropic.models.beta.messages.*` — class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`: + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaToolBash20250124; +import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120; +import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addBeta("mcp-client-2025-11-20") + .addTool(BetaToolBash20250124.builder().build()) + .addTool(BetaCodeExecutionTool20260120.builder().build()) + .addMcpServer(BetaRequestMcpServerUrlDefinition.builder() + .name("my-server") + .url("https://example.com/mcp") + .build()) + .addUserMessage("...") + .build(); + +client.beta().messages().create(params); +``` + +`BetaTool*` types are NOT interchangeable with non-beta `Tool*` — pick one namespace per request. + +**Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` — there is NO typed `.input()`. For code execution results, unwrap two levels: + +```java +for (ContentBlock block : response.content()) { + block.serverToolUse().ifPresent(stu -> { + System.out.println("tool: " + stu.name() + " input: " + stu._input()); + }); + block.codeExecutionToolResult().ifPresent(r -> { + r.content().resultBlock().ifPresent(result -> { + System.out.println("stdout: " + result.stdout()); + System.out.println("stderr: " + result.stderr()); + System.out.println("exit: " + result.returnCode()); + }); + }); +} +``` + +--- + +## Files API (Beta) + +Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant). + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.files.FileMetadata; +import com.anthropic.models.beta.messages.BetaRequestDocumentBlock; +import java.nio.file.Paths; + +FileMetadata meta = client.beta().files().upload( + FileUploadParams.builder() + .file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[]) + .build()); + +// Reference in a beta message: +BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder() + .fileSource(meta.id()) + .build(); +``` + +Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`. diff --git a/junie/versions/2206.3/skills/claude-api/java/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/java/managed-agents/README.md new file mode 100644 index 0000000..49398bc --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/java/managed-agents/README.md @@ -0,0 +1,442 @@ +# Managed Agents — Java + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Java. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Java SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```xml + + com.anthropic + anthropic-java + +``` + +## Client Initialization + +```java +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (uses ANTHROPIC_API_KEY env var) +var client = AnthropicOkHttpClient.fromEnv(); +``` + +--- + +## Create an Environment + +```java +import com.anthropic.models.beta.environments.BetaCloudConfigParams; +import com.anthropic.models.beta.environments.EnvironmentCreateParams; +import com.anthropic.models.beta.environments.UnrestrictedNetwork; + +var environment = client.beta().environments().create(EnvironmentCreateParams.builder() + .name("my-dev-env") + .config(BetaCloudConfigParams.builder() + .networking(UnrestrictedNetwork.builder().build()) + .build()) + .build()); +System.out.println("Environment ID: " + environment.id()); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Model, system, and tools live on the agent object, not the session. Always start with `client.beta().agents().create()` — the session takes either `.agent(agent.id())` or the typed `BetaManagedAgentsAgentParams.builder()...build()`. + +### Minimal + +```java +import com.anthropic.models.beta.agents.AgentCreateParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params; +import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams; +import com.anthropic.models.beta.sessions.SessionCreateParams; + +// 1. Create the agent (reusable, versioned) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("Coding Assistant") + .model("claude-opus-4-6") + .system("You are a helpful coding assistant.") + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .build()); + +// 2. Start a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .title("Quickstart session") + .build()); +System.out.println("Session ID: " + session.id()); +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```java +import com.anthropic.models.beta.agents.AgentUpdateParams; + +var updatedAgent = client.beta().agents().update(agent.id(), AgentUpdateParams.builder() + .version(agent.version()) + .system("You are a helpful coding agent. Always write tests.") + .build()); +System.out.println("New version: " + updatedAgent.version()); + +// List all versions +for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) { + System.out.println("Version " + version.version() + ": " + version.updatedAt()); +} + +// Archive the agent +var archived = client.beta().agents().archive(agent.id()); +System.out.println("Archived at: " + archived.archivedAt().orElseThrow()); +``` + +--- + +## Send a User Message + +```java +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; + +client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Review the auth module") + .build()) + .build()); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```java +import com.anthropic.models.beta.sessions.events.StreamEvents; + +// Open the stream first, then send the user message +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Summarize the repo README") + .build()) + .build()); + + for (var event : (Iterable) stream.stream()::iterator) { + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isAgentToolUse()) { + System.out.println("\n[Using tool: " + event.asAgentToolUse().name() + "]"); + } else if (event.isSessionStatusIdle()) { + break; + } else if (event.isSessionError()) { + System.out.println("\n[Error]"); + break; + } + } +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events. The cross-variant `id` field is read from the raw `_json()` value: + +```java +import com.anthropic.core.JsonValue; +import java.util.HashSet; +import java.util.Map; +import java.util.Optional; + +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + // Stream is open and buffering. List history before tailing live. + var seenEventIds = new HashSet(); + for (var past : client.beta().sessions().events().list(session.id()).autoPager()) { + Optional> obj = past._json().orElseThrow().asObject(); + seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow()); + } + + // Tail live events, skipping anything already seen + for (var event : (Iterable) stream.stream()::iterator) { + Optional> obj = event._json().orElseThrow().asObject(); + if (!seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow())) continue; + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isSessionStatusIdle()) { + break; + } + } +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Java managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-java` repository for the corresponding params types. + +--- + +## Poll Events + +```java +for (var event : client.beta().sessions().events().list(session.id()).autoPager()) { + System.out.println(event.type() + ": " + event); +} +``` + +--- + +## Upload a File + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import java.nio.file.Path; + +var dataCsv = Path.of("data.csv"); + +var file = client.beta().files().upload(FileUploadParams.builder() + .file(dataCsv) + .build()); +System.out.println("File ID: " + file.id()); + +// Mount in a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addResource(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .mountPath("/workspace/data.csv") + .build()) + .build()); +``` + +### Add and Manage Resources on an Existing Session + +```java +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +// Attach an additional file to an open session +var resource = client.beta().sessions().resources().add(session.id(), ResourceAddParams.builder() + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .build()) + .build()); +System.out.println(resource.id()); // "sesrsc_01ABC..." + +// List resources on the session — entries are a discriminated union +var listed = client.beta().sessions().resources().list(session.id()); +for (var entry : listed.data()) { + if (entry.isFile()) { + var fileResource = entry.asFile(); + System.out.println(fileResource.id() + " " + fileResource.type()); + } else if (entry.isGitHubRepository()) { + var repoResource = entry.asGitHubRepository(); + System.out.println(repoResource.id() + " " + repoResource.type()); + } +} + +// Detach a resource +client.beta().sessions().resources().delete(resource.id(), ResourceDeleteParams.builder() + .sessionId(session.id()) + .build()); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Java in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-java` repository for the file list/download bindings. + +--- + +## Session Management + +```java +// List environments +var environments = client.beta().environments().list(); + +// Retrieve a specific environment +var env = client.beta().environments().retrieve(environment.id()); + +// Archive an environment (read-only, existing sessions continue) +client.beta().environments().archive(environment.id()); + +// Delete an environment (only if no sessions reference it) +client.beta().environments().delete(environment.id()); + +// Delete a session +client.beta().sessions().delete(session.id()); +``` + +--- + +## MCP Server Integration + +```java +import com.anthropic.models.beta.agents.BetaManagedAgentsMcpToolsetParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsUrlmcpServerParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("GitHub Assistant") + .model("claude-opus-4-6") + .addMcpServer(BetaManagedAgentsUrlmcpServerParams.builder() + .type(BetaManagedAgentsUrlmcpServerParams.Type.URL) + .name("github") + .url("https://api.githubcopilot.com/mcp/") + .build()) + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .addTool(BetaManagedAgentsMcpToolsetParams.builder() + .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) + .mcpServerName("github") + .build()) + .build()); + +// Session attaches vault(s) containing credentials for those MCP server URLs +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .build()); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.beta.vaults.VaultCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshUpdateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthUpdateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; +import java.time.OffsetDateTime; + +// Create a vault +var vault = client.beta().vaults().create(VaultCreateParams.builder() + .displayName("Alice") + .metadata(VaultCreateParams.Metadata.builder() + .putAdditionalProperty("external_user_id", JsonValue.from("usr_abc123")) + .build()) + .build()); +System.out.println(vault.id()); // "vlt_01ABC..." + +// Add an OAuth credential +var credential = client.beta().vaults().credentials().create(vault.id(), + CredentialCreateParams.builder() + .displayName("Alice's Slack") + .auth(BetaManagedAgentsMcpOAuthCreateParams.builder() + .type(BetaManagedAgentsMcpOAuthCreateParams.Type.MCP_OAUTH) + .mcpServerUrl("https://mcp.slack.com/mcp") + .accessToken("xoxp-...") + .expiresAt(OffsetDateTime.parse("2026-04-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshParams.builder() + .tokenEndpoint("https://slack.com/api/oauth.v2.access") + .clientId("1234567890.0987654321") + .scope("channels:read chat:write") + .refreshToken("xoxe-1-...") + .clientSecretPostTokenEndpointAuth("abc123...") + .build()) + .build()) + .build()); + +// Rotate the credential (e.g., after a token refresh) +client.beta().vaults().credentials().update(credential.id(), + CredentialUpdateParams.builder() + .vaultId(vault.id()) + .auth(BetaManagedAgentsMcpOAuthUpdateParams.builder() + .type(BetaManagedAgentsMcpOAuthUpdateParams.Type.MCP_OAUTH) + .accessToken("xoxp-new-...") + .expiresAt(OffsetDateTime.parse("2026-05-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshUpdateParams.builder() + .refreshToken("xoxe-1-new-...") + .build()) + .build()) + .build()); + +// Archive a vault +client.beta().vaults().archive(vault.id()); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```java +import com.anthropic.models.beta.sessions.BetaManagedAgentsGitHubRepositoryResourceParams; + +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/repo") + .mountPath("/workspace/repo") + .authorizationToken("ghp_your_github_token") + .build()) + .build()); +``` + +Multiple repositories on the same session: + +```java +import java.util.List; + +var resources = List.of( + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/frontend") + .mountPath("/workspace/frontend") + .authorizationToken("ghp_your_github_token") + .build(), + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/backend") + .mountPath("/workspace/backend") + .authorizationToken("ghp_your_github_token") + .build()); +``` + +Rotating a repository's authorization token: + +```java +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; + +var listed = client.beta().sessions().resources().list(session.id()); +var repoResourceId = listed.data().get(0).asGitHubRepository().id(); + +client.beta().sessions().resources().update(repoResourceId, ResourceUpdateParams.builder() + .sessionId(session.id()) + .authorizationToken("ghp_your_new_github_token") + .build()); +``` diff --git a/junie/versions/2206.3/skills/claude-api/php/claude-api.md b/junie/versions/2206.3/skills/claude-api/php/claude-api.md new file mode 100644 index 0000000..cec5ead --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/php/claude-api.md @@ -0,0 +1,375 @@ +# Claude API — PHP + +> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Using API key from environment variable +$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY")); +``` + +### Amazon Bedrock + +```php +use Anthropic\Bedrock; + +// Constructor is private — use the static factory. Reads AWS credentials from env. +$client = Bedrock\Client::fromEnvironment(region: 'us-east-1'); +``` + +### Google Vertex AI + +```php +use Anthropic\Vertex; + +// Constructor is private. Parameter is `location`, not `region`. +$client = Vertex\Client::fromEnvironment( + location: 'us-east5', + projectId: 'my-project-id', +); +``` + +### Anthropic Foundry + +```php +use Anthropic\Foundry; + +// Constructor is private. baseUrl or resource is required. +$client = Foundry\Client::withCredentials( + authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'), + baseUrl: 'https://.services.ai.azure.com/anthropic', +); +``` + +--- + +## Basic Message Request + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [ + ['role' => 'user', 'content' => 'What is the capital of France?'], + ], +); + +// content is an array of polymorphic blocks (TextBlock, ToolUseBlock, +// ThinkingBlock). Accessing ->text on content[0] without checking the block +// type will throw if the first block is not a TextBlock (e.g., when extended +// thinking is enabled and a ThinkingBlock comes first). Always guard: +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +If you only want the first text block: + +```php +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + break; + } +} +``` + +--- + +## Streaming + +> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"` + +```php +use Anthropic\Messages\RawContentBlockDeltaEvent; +use Anthropic\Messages\TextDelta; + +$stream = $client->messages->createStream( + model: 'claude-opus-4-6', + maxTokens: 64000, + messages: [ + ['role' => 'user', 'content' => 'Write a haiku'], + ], +); + +foreach ($stream as $event) { + if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) { + echo $event->delta->text; + } +} +``` + +--- + +## Tool Use + +### Tool Runner (Beta) + +**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure: + +```php +use Anthropic\Lib\Tools\BetaRunnableTool; + +$weatherTool = new BetaRunnableTool( + definition: [ + 'name' => 'get_weather', + 'description' => 'Get the current weather for a location.', + 'input_schema' => [ + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], + run: function (array $input): string { + return "The weather in {$input['location']} is sunny and 72°F."; + }, +); + +$runner = $client->beta->messages->toolRunner( + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']], + model: 'claude-opus-4-6', + tools: [$weatherTool], +); + +foreach ($runner as $message) { + foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } + } +} +``` + +### Manual Loop + +Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. + +```php +use Anthropic\Messages\ToolUseBlock; + +$tools = [ + [ + 'name' => 'get_weather', + 'description' => 'Get the current weather in a given location', + 'inputSchema' => [ // camelCase, not input_schema + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], +]; + +$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']]; + +$response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, +); + +while ($response->stopReason === 'tool_use') { // camelCase property + $toolResults = []; + foreach ($response->content as $block) { + if ($block instanceof ToolUseBlock) { + // $block->name : string — tool name to dispatch on + // $block->input : array — parsed JSON input + // $block->id : string — pass back as toolUseID + $result = executeYourTool($block->name, $block->input); + $toolResults[] = [ + 'type' => 'tool_result', + 'toolUseID' => $block->id, // camelCase, not tool_use_id + 'content' => $result, + ]; + } + } + + // Append assistant turn + user turn with tool results + $messages[] = ['role' => 'assistant', 'content' => $response->content]; + $messages[] = ['role' => 'user', 'content' => $toolResults]; + + $response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, + ); +} + +// Final text response +foreach ($response->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan. + + +--- + +## Extended Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```php +use Anthropic\Messages\ThinkingBlock; + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + thinking: ['type' => 'adaptive'], + messages: [ + ['role' => 'user', 'content' => 'Solve: 27 * 453'], + ], +); + +// ThinkingBlock(s) precede TextBlock in content +foreach ($message->content as $block) { + if ($block instanceof ThinkingBlock) { + echo "Thinking:\n{$block->thinking}\n\n"; + // $block->signature is an opaque string — preserve verbatim if + // passing thinking blocks back in multi-turn conversations + } elseif ($block->type === 'text') { + echo "Answer: {$block->text}\n"; + } +} +``` + +> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan. + +--- + +## Prompt Caching + +`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + system: [ + ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']], + ], + messages: [['role' => 'user', 'content' => 'Summarize the key points']], +); +``` + +For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block. + +Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`. + +--- + +## Structured Outputs + +### Using StructuredOutputModel (Recommended) + +Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`: + +```php +use Anthropic\Lib\Contracts\StructuredOutputModel; +use Anthropic\Lib\Concerns\StructuredOutputModelTrait; +use Anthropic\Lib\Attributes\Constrained; + +class Person implements StructuredOutputModel +{ + use StructuredOutputModelTrait; + + #[Constrained(description: 'Full name')] + public string $name; + + public int $age; + + public ?string $email = null; // nullable = optional field +} + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']], + outputConfig: ['format' => Person::class], +); + +$person = $message->parsedOutput(); // Person instance +echo $person->name; +``` + +Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields. + +### Raw Schema + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']], + outputConfig: [ + 'format' => [ + 'type' => 'json_schema', + 'schema' => [ + 'type' => 'object', + 'properties' => [ + 'name' => ['type' => 'string'], + 'email' => ['type' => 'string'], + 'plan' => ['type' => 'string'], + ], + 'required' => ['name', 'email', 'plan'], + 'additionalProperties' => false, + ], + ], + ], +); + +// First text block contains valid JSON +foreach ($message->content as $block) { + if ($block->type === 'text') { + $data = json_decode($block->text, true); + break; + } +} +``` + +--- + +## Beta Features & Server-Side Tools + +**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header: + +```php +use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition; + +$response = $client->beta->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + mcpServers: [ + BetaRequestMCPServerURLDefinition::with( + name: 'my-server', + url: 'https://example.com/mcp', + ), + ], + betas: ['mcp-client-2025-11-20'], // only valid on ->beta->messages + messages: [['role' => 'user', 'content' => 'Use the MCP tools']], +); +``` + +**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these. diff --git a/junie/versions/2206.3/skills/claude-api/php/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/php/managed-agents/README.md new file mode 100644 index 0000000..1c8673c --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/php/managed-agents/README.md @@ -0,0 +1,435 @@ +# Managed Agents — PHP + +> **Bindings not shown here:** This README covers the most common managed-agents flows for PHP. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the PHP SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Default (uses ANTHROPIC_API_KEY env var) +$client = new Client(); + +// Explicit API key +$client = new Client(apiKey: 'your-api-key'); +``` + +--- + +## Create an Environment + +```php +$environment = $client->beta->environments->create( + name: 'my-dev-env', + config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']], +); +echo "Environment ID: {$environment->id}\n"; // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `$client->beta->agents->create()` — the session takes either `agent: $agent->id` or the typed `BetaManagedAgentsAgentParams::with(type: 'agent', id: $agent->id, version: $agent->version)`. + +### Minimal + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; + +// 1. Create the agent (reusable, versioned) +$agent = $client->beta->agents->create( + name: 'Coding Assistant', + model: 'claude-opus-4-6', + system: 'You are a helpful coding assistant.', + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with( + type: 'agent_toolset_20260401', + ), + ], +); + +// 2. Start a session +$session = $client->beta->sessions->create( + agent: ['type' => 'agent', 'id' => $agent->id, 'version' => $agent->version], + environmentID: $environment->id, + title: 'Quickstart session', +); +echo "Session ID: {$session->id}\n"; +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```php +$updatedAgent = $client->beta->agents->update( + $agent->id, + version: $agent->version, + system: 'You are a helpful coding agent. Always write tests.', +); +echo "New version: {$updatedAgent->version}\n"; + +// List all versions +foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) { + echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n"; +} + +// Archive the agent +$archived = $client->beta->agents->archive($agent->id); +echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n"; +``` + +--- + +## Send a User Message + +```php +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Review the auth module']], + ], + ], +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +> ℹ️ **Streaming transporter:** PHP's default buffered PSR-18 client never returns for the open-ended session event stream. Use a streaming Guzzle transporter for `streamStream()` calls — other calls keep the default client. + +```php +$streamingClient = new GuzzleHttp\Client(['stream' => true]); + +// Open the stream first, then send the user message +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Summarize the repo README']], + ], + ], +); + +foreach ($stream as $event) { + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + 'agent.tool_use' => print("\n[Using tool: {$event->name}]\n"), + 'session.error' => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'), + default => null, + }; + if ($event->type === 'session.status_idle' || $event->type === 'session.error') { + break; + } +} +$stream->close(); +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```php +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); + +// Stream is open and buffering. List history before tailing live. +$seenEventIds = []; +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + $seenEventIds[$event->id] = true; +} + +// Tail live events, skipping anything already seen +foreach ($stream as $event) { + if (isset($seenEventIds[$event->id])) { + continue; + } + $seenEventIds[$event->id] = true; + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + default => null, + }; + if ($event->type === 'session.status_idle') { + break; + } +} +$stream->close(); +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The PHP managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-ai/sdk` PHP repository for the corresponding params. + +--- + +## Poll Events + +```php +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + echo "{$event->type}: {$event->id}\n"; +} +``` + +--- + +## Upload a File + +> ℹ️ **PHP file upload:** The PHP SDK's beta managed-agents file upload binding is not shown in the apps source examples; the canonical PHP example uses raw cURL against `POST /v1/files`. If your codebase prefers the SDK, WebFetch the `anthropic-ai/sdk` PHP repository for the latest binding before writing code. + +```php +use Anthropic\Beta\Sessions\BetaManagedAgentsFileResourceParams; + +// Raw cURL upload (canonical example from the apps source) +$csvPath = 'data.csv'; +$ch = curl_init('https://api.anthropic.com/v1/files'); +curl_setopt_array($ch, [ + CURLOPT_RETURNTRANSFER => true, + CURLOPT_POST => true, + CURLOPT_HTTPHEADER => [ + 'x-api-key: ' . getenv('ANTHROPIC_API_KEY'), + 'anthropic-version: 2023-06-01', + 'anthropic-beta: files-api-2025-04-14', + ], + CURLOPT_POSTFIELDS => ['file' => new CURLFile($csvPath, 'text/csv', 'data.csv')], +]); +$file = json_decode(curl_exec($ch)); +echo "File ID: {$file->id}\n"; + +// Mount in a session +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + resources: [ + BetaManagedAgentsFileResourceParams::with( + type: 'file', + fileID: $file->id, + mountPath: '/workspace/data.csv', + ), + ], +); +``` + +### Add and Manage Resources on an Existing Session + +```php +// Attach an additional file to an open session +$resource = $client->beta->sessions->resources->add( + $session->id, + type: 'file', + fileID: $file->id, +); +echo "{$resource->id}\n"; // "sesrsc_01ABC..." + +// List resources on the session +$listed = $client->beta->sessions->resources->list($session->id); +foreach ($listed->data as $entry) { + echo "{$entry->id} {$entry->type}\n"; +} + +// Detach a resource +$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for PHP in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-ai/sdk` PHP repository for the file list/download bindings. + +--- + +## Session Management + +```php +// List environments +$environments = $client->beta->environments->list(); + +// Retrieve a specific environment +$env = $client->beta->environments->retrieve($environment->id); + +// Archive an environment (read-only, existing sessions continue) +$client->beta->environments->archive($environment->id); + +// Delete an environment (only if no sessions reference it) +$client->beta->environments->delete($environment->id); + +// Delete a session +$client->beta->sessions->delete($session->id); +``` + +--- + +## MCP Server Integration + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; +use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams; +use Anthropic\Beta\Agents\BetaManagedAgentsUrlmcpServerParams; +use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +$agent = $client->beta->agents->create( + name: 'GitHub Assistant', + model: 'claude-opus-4-6', + mcpServers: [ + BetaManagedAgentsUrlmcpServerParams::with( + type: 'url', + name: 'github', + url: 'https://api.githubcopilot.com/mcp/', + ), + ], + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'), + BetaManagedAgentsMCPToolsetParams::with( + type: 'mcp_toolset', + mcpServerName: 'github', + ), + ], +); + +// Session attaches vault(s) containing credentials for those MCP server URLs +$session = $client->beta->sessions->create( + agent: BetaManagedAgentsAgentParams::with( + type: 'agent', + id: $agent->id, + version: $agent->version, + ), + environmentID: $environment->id, + vaultIDs: [$vault->id], +); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```php +// Create a vault +$vault = $client->beta->vaults->create( + displayName: 'Alice', + metadata: ['external_user_id' => 'usr_abc123'], +); +echo $vault->id . "\n"; // "vlt_01ABC..." + +// Add an OAuth credential +$credential = $client->beta->vaults->credentials->create( + vaultID: $vault->id, + displayName: "Alice's Slack", + auth: [ + 'type' => 'mcp_oauth', + 'mcp_server_url' => 'https://mcp.slack.com/mcp', + 'access_token' => 'xoxp-...', + 'expires_at' => '2026-04-15T00:00:00Z', + 'refresh' => [ + 'token_endpoint' => 'https://slack.com/api/oauth.v2.access', + 'client_id' => '1234567890.0987654321', + 'scope' => 'channels:read chat:write', + 'refresh_token' => 'xoxe-1-...', + 'token_endpoint_auth' => [ + 'type' => 'client_secret_post', + 'client_secret' => 'abc123...', + ], + ], + ], +); + +// Rotate the credential (e.g., after a token refresh) +$client->beta->vaults->credentials->update( + $credential->id, + vaultID: $vault->id, + auth: [ + 'type' => 'mcp_oauth', + 'access_token' => 'xoxp-new-...', + 'expires_at' => '2026-05-15T00:00:00Z', + 'refresh' => ['refresh_token' => 'xoxe-1-new-...'], + ], +); + +// Archive a vault +$client->beta->vaults->archive($vault->id); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```php +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + vaultIDs: [$vault->id], + resources: [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/repo', + 'mountPath' => '/workspace/repo', + 'authorizationToken' => 'ghp_your_github_token', + ], + ], +); +``` + +Multiple repositories on the same session: + +```php +$resources = [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/frontend', + 'mountPath' => '/workspace/frontend', + 'authorizationToken' => 'ghp_your_github_token', + ], + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/backend', + 'mountPath' => '/workspace/backend', + 'authorizationToken' => 'ghp_your_github_token', + ], +]; +``` + +Rotating a repository's authorization token: + +```php +$listed = $client->beta->sessions->resources->list($session->id); +$repoResourceId = $listed->data[0]->id; + +$client->beta->sessions->resources->update( + $repoResourceId, + sessionID: $session->id, + authorizationToken: 'ghp_your_new_github_token', +); +``` diff --git a/junie/versions/2206.3/skills/claude-api/python/claude-api/README.md b/junie/versions/2206.3/skills/claude-api/python/claude-api/README.md new file mode 100644 index 0000000..c2acc35 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/claude-api/README.md @@ -0,0 +1,420 @@ +# Claude API — Python + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") + +# Async client +async_client = anthropic.AsyncAnthropic() +``` + +--- + +## Basic Message Request + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[ + {"role": "user", "content": "What is the capital of France?"} + ] +) +# response.content is a list of content block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). Check .type before accessing .text. +for block in response.content: + if block.type == "text": + print(block.text) +``` + +--- + +## System Prompts + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system="You are a helpful coding assistant. Always provide examples in Python.", + messages=[{"role": "user", "content": "How do I read a JSON file?"}] +) +``` + +--- + +## Vision (Images) + +### Base64 + +```python +import base64 + +with open("image.png", "rb") as f: + image_data = base64.standard_b64encode(f.read()).decode("utf-8") + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": image_data + } + }, + {"type": "text", "text": "What's in this image?"} + ] + }] +) +``` + +### URL + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "url", + "url": "https://example.com/image.png" + } + }, + {"type": "text", "text": "Describe this image"} + ] + }] +) +``` + +--- + +## Prompt Caching + +Cache large context to reduce costs (up to 90% savings). **Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block + system="You are an expert on this large document...", + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral"} # default TTL is 5 minutes + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# With explicit TTL (time-to-live) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Verifying Cache Hits + +```python +print(response.usage.cache_creation_input_tokens) # tokens written to cache (~1.25x cost) +print(response.usage.cache_read_input_tokens) # tokens served from cache (~0.1x cost) +print(response.usage.input_tokens) # uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `datetime.now()` or a UUID in the system prompt, unsorted `json.dumps()`, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```python +# Opus 4.6: adaptive thinking (recommended) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + thinking={"type": "adaptive"}, + output_config={"effort": "high"}, # low | medium | high | max + messages=[{"role": "user", "content": "Solve this step by step..."}] +) + +# Access thinking and response +for block in response.content: + if block.type == "thinking": + print(f"Thinking: {block.thinking}") + elif block.type == "text": + print(f"Response: {block.text}") +``` + +--- + +## Error Handling + +```python +import anthropic + +try: + response = client.messages.create(...) +except anthropic.BadRequestError as e: + print(f"Bad request: {e.message}") +except anthropic.AuthenticationError: + print("Invalid API key") +except anthropic.PermissionDeniedError: + print("API key lacks required permissions") +except anthropic.NotFoundError: + print("Invalid model or endpoint") +except anthropic.RateLimitError as e: + retry_after = int(e.response.headers.get("retry-after", "60")) + print(f"Rate limited. Retry after {retry_after}s.") +except anthropic.APIStatusError as e: + if e.status_code >= 500: + print(f"Server error ({e.status_code}). Retry later.") + else: + print(f"API error: {e.message}") +except anthropic.APIConnectionError: + print("Network error. Check internet connection.") +``` + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. + +```python +class ConversationManager: + """Manage multi-turn conversations with the Claude API.""" + + def __init__(self, client: anthropic.Anthropic, model: str, system: str = None): + self.client = client + self.model = model + self.system = system + self.messages = [] + + def send(self, user_message: str, **kwargs) -> str: + """Send a message and get a response.""" + self.messages.append({"role": "user", "content": user_message}) + + response = self.client.messages.create( + model=self.model, + max_tokens=kwargs.get("max_tokens", 16000), + system=self.system, + messages=self.messages, + **kwargs + ) + + assistant_message = next( + (b.text for b in response.content if b.type == "text"), "" + ) + self.messages.append({"role": "assistant", "content": assistant_message}) + + return assistant_message + +# Usage +conversation = ConversationManager( + client=anthropic.Anthropic(), + model="claude-opus-4-6", + system="You are a helpful assistant." +) + +response1 = conversation.send("My name is Alice.") +response2 = conversation.send("What's my name?") # Claude remembers "Alice" +``` + +**Rules:** + +- Messages must alternate between `user` and `assistant` +- First message must be `user` + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```python +import anthropic + +client = anthropic.Anthropic() +messages = [] + +def chat(user_message: str) -> str: + messages.append({"role": "user", "content": user_message}) + + response = client.beta.messages.create( + betas=["compact-2026-01-12"], + model="claude-opus-4-6", + max_tokens=16000, + messages=messages, + context_management={ + "edits": [{"type": "compact_20260112"}] + } + ) + + # Append full content — compaction blocks must be preserved + messages.append({"role": "assistant", "content": response.content}) + + return next(block.text for block in response.content if block.type == "text") + +# Compaction triggers automatically when context grows large +print(chat("Help me build a Python web scraper")) +print(chat("Add support for JavaScript-rendered pages")) +print(chat("Now add rate limiting and error handling")) +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +|-------|---------| +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match your schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```python +# Automatic caching (simplest — caches the last cacheable block) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, + system=large_document_text, # e.g., 50KB of context + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# First request: full cost +# Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Choose the Right Model + +```python +# Default to Opus for most tasks +response = client.messages.create( + model="claude-opus-4-6", # $5.00/$25.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing"}] +) + +# Use Sonnet for high-volume production workloads +standard_response = client.messages.create( + model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize this document"}] +) + +# Use Haiku only for simple, speed-critical tasks +simple_response = client.messages.create( + model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens + max_tokens=256, + messages=[{"role": "user", "content": "Classify this as positive or negative"}] +) +``` + +### 3. Use Token Counting Before Requests + +```python +count_response = client.messages.count_tokens( + model="claude-opus-4-6", + messages=messages, + system=system +) + +estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens +print(f"Estimated input cost: ${estimated_input_cost:.4f}") +``` + +--- + +## Retry with Exponential Backoff + +> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides. + +```python +import time +import random +import anthropic + +def call_with_retry( + client: anthropic.Anthropic, + max_retries: int = 5, + base_delay: float = 1.0, + max_delay: float = 60.0, + **kwargs +): + """Call the API with exponential backoff retry.""" + last_exception = None + + for attempt in range(max_retries): + try: + return client.messages.create(**kwargs) + except anthropic.RateLimitError as e: + last_exception = e + except anthropic.APIStatusError as e: + if e.status_code >= 500: + last_exception = e + else: + raise # Client errors (4xx except 429) should not be retried + + delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) + print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s") + time.sleep(delay) + + raise last_exception +``` diff --git a/junie/versions/2206.3/skills/claude-api/python/claude-api/batches.md b/junie/versions/2206.3/skills/claude-api/python/claude-api/batches.md new file mode 100644 index 0000000..bed5401 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/claude-api/batches.md @@ -0,0 +1,185 @@ +# Message Batches API — Python + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```python +import anthropic +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id="request-1", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize climate change impacts"}] + ) + ), + Request( + custom_id="request-2", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing basics"}] + ) + ), + ] +) + +print(f"Batch ID: {message_batch.id}") +print(f"Status: {message_batch.processing_status}") +``` + +--- + +## Poll for Completion + +```python +import time + +while True: + batch = client.messages.batches.retrieve(message_batch.id) + if batch.processing_status == "ended": + break + print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}") + time.sleep(60) + +print("Batch complete!") +print(f"Succeeded: {batch.request_counts.succeeded}") +print(f"Errored: {batch.request_counts.errored}") +``` + +--- + +## Retrieve Results + +> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead. + +```python +for result in client.messages.batches.results(message_batch.id): + match result.result.type: + case "succeeded": + msg = result.result.message + text = next((b.text for b in msg.content if b.type == "text"), "") + print(f"[{result.custom_id}] {text[:100]}") + case "errored": + if result.result.error.type == "invalid_request": + print(f"[{result.custom_id}] Validation error - fix request and retry") + else: + print(f"[{result.custom_id}] Server error - safe to retry") + case "canceled": + print(f"[{result.custom_id}] Canceled") + case "expired": + print(f"[{result.custom_id}] Expired - resubmit") +``` + +--- + +## Cancel a Batch + +```python +cancelled = client.messages.batches.cancel(message_batch.id) +print(f"Status: {cancelled.processing_status}") # "canceling" +``` + +--- + +## Batch with Prompt Caching + +```python +shared_system = [ + {"type": "text", "text": "You are a literary analyst."}, + { + "type": "text", + "text": large_document_text, # Shared across all requests + "cache_control": {"type": "ephemeral"} + } +] + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id=f"analysis-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + system=shared_system, + messages=[{"role": "user", "content": question}] + ) + ) + for i, question in enumerate(questions) + ] +) +``` + +--- + +## Full End-to-End Example + +```python +import anthropic +import time +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +# 1. Prepare requests +items_to_classify = [ + "The product quality is excellent!", + "Terrible customer service, never again.", + "It's okay, nothing special.", +] + +requests = [ + Request( + custom_id=f"classify-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-haiku-4-5", + max_tokens=50, + messages=[{ + "role": "user", + "content": f"Classify as positive/negative/neutral (one word): {text}" + }] + ) + ) + for i, text in enumerate(items_to_classify) +] + +# 2. Create batch +batch = client.messages.batches.create(requests=requests) +print(f"Created batch: {batch.id}") + +# 3. Wait for completion +while True: + batch = client.messages.batches.retrieve(batch.id) + if batch.processing_status == "ended": + break + time.sleep(10) + +# 4. Collect results +results = {} +for result in client.messages.batches.results(batch.id): + if result.result.type == "succeeded": + msg = result.result.message + results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "") + +for custom_id, classification in sorted(results.items()): + print(f"{custom_id}: {classification}") +``` diff --git a/junie/versions/2206.3/skills/claude-api/python/claude-api/files-api.md b/junie/versions/2206.3/skills/claude-api/python/claude-api/files-api.md new file mode 100644 index 0000000..93efef7 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/claude-api/files-api.md @@ -0,0 +1,165 @@ +# Files API — Python + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```python +import anthropic + +client = anthropic.Anthropic() + +uploaded = client.beta.files.upload( + file=("report.pdf", open("report.pdf", "rb"), "application/pdf"), +) +print(f"File ID: {uploaded.id}") +print(f"Size: {uploaded.size_bytes} bytes") +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```python +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Summarize the key findings in this report."}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id}, + "title": "Q4 Report", # optional + "citations": {"enabled": True} # optional, enables citations + } + ] + }], + betas=["files-api-2025-04-14"], +) +for block in response.content: + if block.type == "text": + print(block.text) +``` + +### Image + +```python +image_file = client.beta.files.upload( + file=("photo.png", open("photo.png", "rb"), "image/png"), +) + +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "What's in this image?"}, + { + "type": "image", + "source": {"type": "file", "file_id": image_file.id} + } + ] + }], + betas=["files-api-2025-04-14"], +) +``` + +--- + +## Manage Files + +### List Files + +```python +files = client.beta.files.list() +for f in files.data: + print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)") +``` + +### Get File Metadata + +```python +file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") +print(f"Filename: {file_info.filename}") +print(f"MIME type: {file_info.mime_type}") +``` + +### Delete a File + +```python +client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") +``` + +### Download a File + +Only files created by the code execution tool or skills can be downloaded (not user-uploaded files). + +```python +file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") +file_content.write_to_file("output.txt") +``` + +--- + +## Full End-to-End Example + +Upload a document once, ask multiple questions about it: + +```python +import anthropic + +client = anthropic.Anthropic() + +# 1. Upload once +uploaded = client.beta.files.upload( + file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"), +) +print(f"Uploaded: {uploaded.id}") + +# 2. Ask multiple questions using the same file_id +questions = [ + "What are the key terms and conditions?", + "What is the termination clause?", + "Summarize the payment schedule.", +] + +for question in questions: + response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": question}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id} + } + ] + }], + betas=["files-api-2025-04-14"], + ) + print(f"\nQ: {question}") + text = next((b.text for b in response.content if b.type == "text"), "") + print(f"A: {text[:200]}") + +# 3. Clean up when done +client.beta.files.delete(uploaded.id) +``` diff --git a/junie/versions/2206.3/skills/claude-api/python/claude-api/streaming.md b/junie/versions/2206.3/skills/claude-api/python/claude-api/streaming.md new file mode 100644 index 0000000..b21f9ae --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/claude-api/streaming.md @@ -0,0 +1,162 @@ +# Streaming — Python + +## Quick Start + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +### Async + +```python +async with async_client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + async for text in stream.text_stream: + print(text, end="", flush=True) +``` + +--- + +## Handling Different Content Types + +Claude may return text, thinking blocks, or tool use. Handle each appropriately: + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + thinking={"type": "adaptive"}, + messages=[{"role": "user", "content": "Analyze this problem"}] +) as stream: + for event in stream: + if event.type == "content_block_start": + if event.content_block.type == "thinking": + print("\n[Thinking...]") + elif event.content_block.type == "text": + print("\n[Response:]") + + elif event.type == "content_block_delta": + if event.delta.type == "thinking_delta": + print(event.delta.thinking, end="", flush=True) + elif event.delta.type == "text_delta": + print(event.delta.text, end="", flush=True) +``` + +--- + +## Streaming with Tool Use + +The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools: + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + tools=tools, + messages=messages +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + response = stream.get_final_message() + # Continue with tool execution if response.stop_reason == "tool_use" +``` + +--- + +## Getting the Final Message + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Hello"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + # Get full message after streaming + final_message = stream.get_final_message() + print(f"\n\nTokens used: {final_message.usage.output_tokens}") +``` + +--- + +## Streaming with Progress Updates + +```python +def stream_with_progress(client, **kwargs): + """Stream a response with progress updates.""" + total_tokens = 0 + content_parts = [] + + with client.messages.stream(**kwargs) as stream: + for event in stream: + if event.type == "content_block_delta": + if event.delta.type == "text_delta": + text = event.delta.text + content_parts.append(text) + print(text, end="", flush=True) + + elif event.type == "message_delta": + if event.usage and event.usage.output_tokens is not None: + total_tokens = event.usage.output_tokens + + final_message = stream.get_final_message() + + print(f"\n\n[Tokens used: {total_tokens}]") + return "".join(content_parts) +``` + +--- + +## Error Handling in Streams + +```python +try: + with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] + ) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +except anthropic.APIConnectionError: + print("\nConnection lost. Please retry.") +except anthropic.RateLimitError: + print("\nRate limited. Please wait and retry.") +except anthropic.APIStatusError as e: + print(f"\nAPI error: {e.status_code}") +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `flush=True` to show tokens immediately +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use timeouts** — Set appropriate timeouts for your application +5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events diff --git a/junie/versions/2206.3/skills/claude-api/python/claude-api/tool-use.md b/junie/versions/2206.3/skills/claude-api/python/claude-api/tool-use.md new file mode 100644 index 0000000..52bbe49 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/claude-api/tool-use.md @@ -0,0 +1,590 @@ +# Tool Use — Python + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the Python SDK. + +Use the `@beta_tool` decorator to define tools as typed functions, then pass them to `client.beta.messages.tool_runner()`: + +```python +import anthropic +from anthropic import beta_tool + +client = anthropic.Anthropic() + +@beta_tool +def get_weather(location: str, unit: str = "celsius") -> str: + """Get current weather for a location. + + Args: + location: City and state, e.g., San Francisco, CA. + unit: Temperature unit, either "celsius" or "fahrenheit". + """ + # Your implementation here + return f"72°F and sunny in {location}" + +# The tool runner handles the agentic loop automatically +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[get_weather], + messages=[{"role": "user", "content": "What's the weather in Paris?"}], +) + +# Each iteration yields a BetaMessage; iteration stops when Claude is done +for message in runner: + print(message) +``` + +For async usage, use `@beta_async_tool` with `async def` functions. + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via decorators +- Tool schemas are generated automatically from function signatures +- Iteration stops automatically when Claude has no more tool calls + +--- + +## MCP Tool Conversion Helpers + +**Beta.** Convert [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires `pip install anthropic[mcp]` (Python 3.10+). + +> **Note:** The Claude API also supports an `mcp_servers` parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection. + +### MCP Tools with Tool Runner + +```python +from anthropic import AsyncAnthropic +from anthropic.lib.tools.mcp import async_mcp_tool +from mcp import ClientSession +from mcp.client.stdio import stdio_client, StdioServerParameters + +client = AsyncAnthropic() + +async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write): + async with ClientSession(read, write) as mcp_client: + await mcp_client.initialize() + + tools_result = await mcp_client.list_tools() + # tool_runner is sync — returns the runner, not a coroutine + runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Use the available tools"}], + tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools], + ) + async for message in runner: + print(message) +``` + +For sync usage, use `mcp_tool` instead of `async_mcp_tool`. + +### MCP Prompts + +```python +from anthropic.lib.tools.mcp import mcp_message + +prompt = await mcp_client.get_prompt(name="my-prompt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[mcp_message(m) for m in prompt.messages], +) +``` + +### MCP Resources as Content + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_content + +resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + mcp_resource_to_content(resource), + {"type": "text", "text": "Summarize this document"}, + ], + }], +) +``` + +### Upload MCP Resources as Files + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_file + +resource = await mcp_client.read_resource(uri="file:///path/to/data.json") +uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource)) +``` + +Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types). + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval): + +```python +import anthropic + +client = anthropic.Anthropic() +tools = [...] # Your tool definitions +messages = [{"role": "user", "content": user_input}] + +# Agentic loop: keep going until Claude stops calling tools +while True: + response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=messages + ) + + # If Claude is done (no more tool calls), break + if response.stop_reason == "end_turn": + break + + # Server-side tool hit iteration limit; re-send to continue + if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_input}, + {"role": "assistant", "content": response.content}, + ] + continue + + # Extract tool use blocks from the response + tool_use_blocks = [b for b in response.content if b.type == "tool_use"] + + # Append assistant's response (including tool_use blocks) + messages.append({"role": "assistant", "content": response.content}) + + # Execute each tool and collect results + tool_results = [] + for tool in tool_use_blocks: + result = execute_tool(tool.name, tool.input) # Your implementation + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool.id, # Must match the tool_use block's id + "content": result + }) + + # Append tool results as a user message + messages.append({"role": "user", "content": tool_results}) + +# Final response text +final_text = next(b.text for b in response.content if b.type == "text") +``` + +--- + +## Handling Tool Results + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) + +for block in response.content: + if block.type == "tool_use": + tool_name = block.name + tool_input = block.input + tool_use_id = block.id + + result = execute_tool(tool_name, tool_input) + + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + {"role": "user", "content": "What's the weather in Paris?"}, + {"role": "assistant", "content": response.content}, + { + "role": "user", + "content": [{ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": result + }] + } + ] + ) +``` + +--- + +## Multiple Tool Calls + +```python +tool_results = [] + +for block in response.content: + if block.type == "tool_use": + result = execute_tool(block.name, block.input) + tool_results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": result + }) + +# Send all results back at once +if tool_results: + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + *previous_messages, + {"role": "assistant", "content": response.content}, + {"role": "user", "content": tool_results} + ] + ) +``` + +--- + +## Error Handling in Tool Results + +```python +tool_result = { + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": "Error: Location 'xyz' not found. Please provide a valid city name.", + "is_error": True +} +``` + +--- + +## Tool Choice + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) +``` + +--- + +## Code Execution + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" + }], + tools=[{ + "type": "code_execution_20260120", + "name": "code_execution" + }] +) + +for block in response.content: + if block.type == "text": + print(block.text) + elif block.type == "bash_code_execution_tool_result": + print(f"stdout: {block.content.stdout}") +``` + +### Upload Files for Analysis + +```python +# 1. Upload a file +uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb")) + +# 2. Pass to code execution via container_upload block +# Code execution is GA; Files API is still beta (pass via extra_headers) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + extra_headers={"anthropic-beta": "files-api-2025-04-14"}, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."}, + {"type": "container_upload", "file_id": uploaded.id} + ] + }], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Retrieve Generated Files + +```python +import os + +OUTPUT_DIR = "./claude_outputs" +os.makedirs(OUTPUT_DIR, exist_ok=True) + +for block in response.content: + if block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result" and result.content: + for file_ref in result.content: + if file_ref.type == "bash_code_execution_output": + metadata = client.beta.files.retrieve_metadata(file_ref.file_id) + file_content = client.beta.files.download(file_ref.file_id) + # Use basename to prevent path traversal; validate result + safe_name = os.path.basename(metadata.filename) + if not safe_name or safe_name in (".", ".."): + print(f"Skipping invalid filename: {metadata.filename}") + continue + output_path = os.path.join(OUTPUT_DIR, safe_name) + file_content.write_to_file(output_path) + print(f"Saved: {output_path}") +``` + +### Container Reuse + +```python +# First request: set up environment +response1 = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) + +# Get container ID from response +container_id = response1.container.id + +# Second request: reuse the same container +response2 = client.messages.create( + container=container_id, + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Response Structure + +```python +for block in response.content: + if block.type == "text": + print(block.text) # Claude's explanation + elif block.type == "server_tool_use": + print(f"Running: {block.name} - {block.input}") # What Claude is doing + elif block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result": + if result.return_code == 0: + print(f"Output: {result.stdout}") + else: + print(f"Error: {result.stderr}") + else: + print(f"Tool error: {result.error_code}") + elif block.type == "text_editor_code_execution_tool_result": + print(f"File operation: {block.content}") +``` + +--- + +## Memory Tool + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Remember that my preferred language is Python."}], + tools=[{"type": "memory_20250818", "name": "memory"}], +) +``` + +### SDK Memory Helper + +Subclass `BetaAbstractMemoryTool`: + +```python +from anthropic.lib.tools import BetaAbstractMemoryTool + +class MyMemoryTool(BetaAbstractMemoryTool): + def view(self, command): ... + def create(self, command): ... + def str_replace(self, command): ... + def insert(self, command): ... + def delete(self, command): ... + def rename(self, command): ... + +memory = MyMemoryTool() + +# Use with tool runner +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[memory], + messages=[{"role": "user", "content": "Remember my preferences"}], +) + +for message in runner: + print(message) +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py` + +--- + +## Structured Outputs + +### JSON Outputs (Pydantic — Recommended) + +```python +from pydantic import BaseModel +from typing import List +import anthropic + +class ContactInfo(BaseModel): + name: str + email: str + plan: str + interests: List[str] + demo_requested: bool + +client = anthropic.Anthropic() + +response = client.messages.parse( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo." + }], + output_format=ContactInfo, +) + +# response.parsed_output is a validated ContactInfo instance +contact = response.parsed_output +print(contact.name) # "Jane Doe" +print(contact.interests) # ["API", "SDKs"] +``` + +### Raw Schema + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract info: John Smith (john@example.com) wants the Enterprise plan." + }], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "email": {"type": "string"}, + "plan": {"type": "string"}, + "demo_requested": {"type": "boolean"} + }, + "required": ["name", "email", "plan", "demo_requested"], + "additionalProperties": False + } + } + } +) + +import json +# output_config.format guarantees the first block is text with valid JSON +text = next(b.text for b in response.content if b.type == "text") +data = json.loads(text) +``` + +### Strict Tool Use + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}], + tools=[{ + "name": "book_flight", + "description": "Book a flight to a destination", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"}, + "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]} + }, + "required": ["destination", "date", "passengers"], + "additionalProperties": False + } + }] +) +``` + +### Using Both Together + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Plan a trip to Paris next month"}], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "summary": {"type": "string"}, + "next_steps": {"type": "array", "items": {"type": "string"}} + }, + "required": ["summary", "next_steps"], + "additionalProperties": False + } + } + }, + tools=[{ + "name": "search_flights", + "description": "Search for available flights", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"} + }, + "required": ["destination", "date"], + "additionalProperties": False + } + }] +) +``` diff --git a/junie/versions/2206.3/skills/claude-api/python/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/python/managed-agents/README.md new file mode 100644 index 0000000..49b6783 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/python/managed-agents/README.md @@ -0,0 +1,329 @@ +# Managed Agents — Python + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") +``` + +--- + +## Create an Environment + +```python +environment = client.beta.environments.create( + name="my-dev-env", + config={ + "type": "cloud", + "networking": {"type": "unrestricted"}, + }, +) +print(environment.id) # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent={"type": "agent", "id": agent.id}`. + +### Minimal + +```python +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name="Coding Assistant", + model="claude-opus-4-6", + tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}], +) + +# 2. Start a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, +) +print(session.id, session.status) +``` + +### With system prompt and custom tools + +```python +import os + +agent = client.beta.agents.create( + name="Code Reviewer", + model="claude-opus-4-6", + system="You are a senior code reviewer.", + tools=[ + {"type": "agent_toolset_20260401"}, + { + "type": "custom", + "name": "run_tests", + "description": "Run the test suite", + "input_schema": { + "type": "object", + "properties": { + "test_path": {"type": "string", "description": "Path to test file"} + }, + "required": ["test_path"], + }, + }, + ], +) + +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + title="Code review session", + resources=[ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], + "branch": "main", + } + ], +) +``` + +--- + +## Send a User Message + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.message", + "content": [{"type": "text", "text": "Review the auth module"}], + } + ], +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```python +import json + +# Stream-first: open stream, then send while stream is live +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + client.beta.sessions.events.send( + session_id=session.id, + events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}], + ) + for event in stream: + ... # process events + +# Standalone stream iteration: +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + # Custom tool invocation — session is now idle + print(f"\nCustom tool call: {event.tool_name}") + print(f"Input: {json.dumps(event.input)}") + # Send result back (see below) + elif event.type == "session.status_idle": + print("\n--- Agent idle ---") + elif event.type == "session.status_terminated": + print("\n--- Session terminated ---") + break +``` + +--- + +## Provide Custom Tool Result + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{"type": "text", "text": "All 42 tests passed."}], + } + ], +) +``` + +--- + +## Poll Events + +```python +events = client.beta.sessions.events.list( + session_id=session.id, +) +for event in events.data: + print(f"{event.type}: {event.id}") +``` + +> ⚠️ **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration — both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events). + +--- + +## Full Streaming Loop with Custom Tools + +```python +import json + + +def run_custom_tool(tool_name: str, tool_input: dict) -> str: + """Execute a custom tool and return the result.""" + if tool_name == "run_tests": + # Your tool implementation here + return "All tests passed." + return f"Unknown tool: {tool_name}" + + +def run_session(client, session_id: str): + """Stream events and handle custom tool calls.""" + while True: + with client.beta.sessions.stream( + session_id=session_id, + ) as stream: + tool_calls = [] + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + tool_calls.append(event) + elif event.type == "session.status_idle": + break + elif event.type == "session.status_terminated": + return + + if not tool_calls: + break + + # Process custom tool calls + results = [] + for call in tool_calls: + result = run_custom_tool(call.tool_name, call.input) + results.append({ + "type": "user.custom_tool_result", + "custom_tool_use_id": call.id, + "content": [{"type": "text", "text": result}], + }) + + client.beta.sessions.events.send( + session_id=session_id, + events=results, + ) +``` + +--- + +## Upload a File + +```python +with open("data.csv", "rb") as f: + file = client.beta.files.upload( + file=f, + ) + +# Use in a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}], +) +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```python +# List files associated with a session +files = client.beta.files.list(session_id=session.id) +for f in files.data: + print(f.filename, f.size_bytes) + # Download each file and save to disk + file_content = client.beta.files.download(f.id) + file_content.write_to_file(f.filename) +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list` (with `scope=session_id` as a query param). Retry once or twice if the list is empty. + +--- + +## Session Management + +```python +# Get session details +session = client.beta.sessions.retrieve(session_id="sess_abc123") +print(session.status, session.usage) + +# List sessions +sessions = client.beta.sessions.list() + +# Delete a session +client.beta.sessions.delete(session_id="sess_abc123") + +# Archive a session +client.beta.sessions.archive(session_id="sess_abc123") +``` + +--- + +## MCP Server Integration + +```python +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name="MCP Agent", + model="claude-opus-4-6", + mcp_servers=[ + {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"}, + ], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "my-tools"}, + ], +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment.id, + vault_ids=[vault.id], +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2206.3/skills/claude-api/ruby/claude-api.md b/junie/versions/2206.3/skills/claude-api/ruby/claude-api.md new file mode 100644 index 0000000..21f5b12 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/ruby/claude-api.md @@ -0,0 +1,113 @@ +# Claude API — Ruby + +> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +--- + +## Basic Message Request + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "What is the capital of France?" } + ] +) +# content is an array of polymorphic block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text". +# .text raises NoMethodError on non-TextBlock entries. +message.content.each do |block| + puts block.text if block.type == :text +end +``` + +--- + +## Streaming + +```ruby +stream = client.messages.stream( + model: :"claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a haiku" }] +) + +stream.text.each { |text| print(text) } +``` + +--- + +## Tool Use + +The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution. + +### Tool Runner (Beta) + +```ruby +class GetWeatherInput < Anthropic::BaseModel + required :location, String, doc: "City and state, e.g. San Francisco, CA" +end + +class GetWeather < Anthropic::BaseTool + doc "Get the current weather for a location" + + input_schema GetWeatherInput + + def call(input) + "The weather in #{input.location} is sunny and 72°F." + end +end + +client.beta.messages.tool_runner( + model: :"claude-opus-4-6", + max_tokens: 16000, + tools: [GetWeather.new], + messages: [{ role: "user", content: "What's the weather in San Francisco?" }] +).each_message do |message| + puts message.content +end +``` + +### Manual Loop + +See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. + +--- + +## Prompt Caching + +`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + system_: [ + { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } } + ], + messages: [{ role: "user", content: "Summarize the key points" }] +) +``` + +For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block. + +Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`. diff --git a/junie/versions/2206.3/skills/claude-api/ruby/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/ruby/managed-agents/README.md new file mode 100644 index 0000000..e6bf24f --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/ruby/managed-agents/README.md @@ -0,0 +1,389 @@ +# Managed Agents — Ruby + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +> ⚠️ **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code. + +--- + +## Create an Environment + +```ruby +environment = client.beta.environments.create( + name: "my-dev-env", + config: { + type: "cloud", + networking: {type: "unrestricted"} + } +) +puts "Environment ID: #{environment.id}" # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` — the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`. + +### Minimal + +```ruby +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name: "Coding Assistant", + model: :"claude-opus-4-6", + system_: "You are a helpful coding assistant.", + tools: [{type: "agent_toolset_20260401"}] +) + +# 2. Start a session +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + title: "Quickstart session" +) +puts "Session ID: #{session.id}" +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```ruby +updated_agent = client.beta.agents.update( + agent.id, + version: agent.version, + system_: "You are a helpful coding agent. Always write tests." +) +puts "New version: #{updated_agent.version}" + +# List all versions +client.beta.agents.versions.list(agent.id).auto_paging_each do |version| + puts "Version #{version.version}: #{version.updated_at.iso8601}" +end + +# Archive the agent +archived = client.beta.agents.archive(agent.id) +puts "Archived at: #{archived.archived_at.iso8601}" +``` + +--- + +## Send a User Message + +```ruby +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Review the auth module"}] + }] +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```ruby +# Open the stream first, then send the user message +stream = client.beta.sessions.events.stream_events(session.id) + +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Summarize the repo README"}] + }] +) + +stream.each do |event| + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"agent.tool_use" + puts "\n[Using tool: #{event.name}]" + in :"session.status_idle" + break + in :"session.error" + puts "\n[Error: #{event.error&.message || "unknown"}]" + break + else + # ignore other event types + end +end +``` + +> ℹ️ Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`). + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```ruby +require "set" + +stream = client.beta.sessions.events.stream_events(session.id) + +# Stream is open and buffering. List history before tailing live. +seen_event_ids = Set.new +client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id } + +# Tail live events, skipping anything already seen +stream.each do |event| + next if seen_event_ids.include?(event.id) + seen_event_ids << event.id + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"session.status_idle" + break + else + # ignore other event types + end +end +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params. + +--- + +## Poll Events + +```ruby +client.beta.sessions.events.list(session.id).auto_paging_each do |event| + puts "#{event.type}: #{event.id}" +end +``` + +--- + +## Upload a File + +```ruby +require "pathname" + +file = client.beta.files.upload(file: Pathname("data.csv")) +puts "File ID: #{file.id}" + +# Mount in a session +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + resources: [ + { + type: "file", + file_id: file.id, + mount_path: "/workspace/data.csv" + } + ] +) +``` + +### Add and Manage Resources on an Existing Session + +```ruby +# Attach an additional file to an open session +resource = client.beta.sessions.resources.add( + session.id, + type: "file", + file_id: file.id +) +puts resource.id # "sesrsc_01ABC..." + +# List resources on the session +listed = client.beta.sessions.resources.list(session.id) +listed.data.each { |entry| puts "#{entry.id} #{entry.type}" } + +# Detach a resource +client.beta.sessions.resources.delete(resource.id, session_id: session.id) +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Ruby in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic` Ruby gem repository for the file list/download bindings. + +--- + +## Session Management + +```ruby +# List environments +environments = client.beta.environments.list + +# Retrieve a specific environment +env = client.beta.environments.retrieve(environment.id) + +# Archive an environment (read-only, existing sessions continue) +client.beta.environments.archive(environment.id) + +# Delete an environment (only if no sessions reference it) +client.beta.environments.delete(environment.id) + +# Delete a session +client.beta.sessions.delete(session.id) +``` + +--- + +## MCP Server Integration + +```ruby +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name: "GitHub Assistant", + model: :"claude-opus-4-6", + mcp_servers: [ + { + type: "url", + name: "github", + url: "https://api.githubcopilot.com/mcp/" + } + ], + tools: [ + {type: "agent_toolset_20260401"}, + {type: "mcp_toolset", mcp_server_name: "github"} + ] +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + vault_ids: [vault.id] +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```ruby +# Create a vault +vault = client.beta.vaults.create( + display_name: "Alice", + metadata: {external_user_id: "usr_abc123"} +) +puts vault.id # "vlt_01ABC..." + +# Add an OAuth credential +credential = client.beta.vaults.credentials.create( + vault.id, + display_name: "Alice's Slack", + auth: { + type: "mcp_oauth", + mcp_server_url: "https://mcp.slack.com/mcp", + access_token: "xoxp-...", + expires_at: "2026-04-15T00:00:00Z", + refresh: { + token_endpoint: "https://slack.com/api/oauth.v2.access", + client_id: "1234567890.0987654321", + scope: "channels:read chat:write", + refresh_token: "xoxe-1-...", + token_endpoint_auth: { + type: "client_secret_post", + client_secret: "abc123..." + } + } + } +) + +# Rotate the credential (e.g., after a token refresh) +client.beta.vaults.credentials.update( + credential.id, + vault_id: vault.id, + auth: { + type: "mcp_oauth", + access_token: "xoxp-new-...", + expires_at: "2026-05-15T00:00:00Z", + refresh: {refresh_token: "xoxe-1-new-..."} + } +) + +# Archive a vault +client.beta.vaults.archive(vault.id) +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```ruby +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], + resources: [ + { + type: "github_repository", + url: "https://github.com/org/repo", + mount_path: "/workspace/repo", + authorization_token: "ghp_your_github_token" + } + ] +) +``` + +Multiple repositories on the same session: + +```ruby +resources = [ + { + type: "github_repository", + url: "https://github.com/org/frontend", + mount_path: "/workspace/frontend", + authorization_token: "ghp_your_github_token" + }, + { + type: "github_repository", + url: "https://github.com/org/backend", + mount_path: "/workspace/backend", + authorization_token: "ghp_your_github_token" + } +] +``` + +Rotating a repository's authorization token: + +```ruby +listed = client.beta.sessions.resources.list(session.id) +repo_resource_id = listed.data.first.id + +client.beta.sessions.resources.update( + repo_resource_id, + session_id: session.id, + authorization_token: "ghp_your_new_github_token" +) +``` diff --git a/junie/versions/2206.3/skills/claude-api/shared/agent-design.md b/junie/versions/2206.3/skills/claude-api/shared/agent-design.md new file mode 100644 index 0000000..6756c39 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/agent-design.md @@ -0,0 +1,101 @@ +# Agent Design Patterns + +This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders. + +--- + +## Model Parameters + +| Parameter | When to use it | What to expect | +| --- | --- | --- | +| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. | +| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. | + +See `SKILL.md` §Thinking & Effort for model support and parameter details. + +--- + +## Designing Your Tool Surface + +### Bash vs. dedicated tools + +Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do. + +A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit. + +**When to promote an action to a dedicated tool:** + +- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not. +- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant. +- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered. +- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize. + +**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action. + +--- + +## Anthropic-Provided Tools + +| Tool | Side | When to use it | What to expect | +| --- | --- | --- | --- | +| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. | +| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. | +| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. | +| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. | +| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. | +| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. | + +**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest. + +--- + +## Composing Tool Calls: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again. + +**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude. + +| When to use it | What to expect | +| --- | --- | +| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. | + +--- + +## Scaling the Tool and Instruction Set + +| Feature | When to use it | What to expect | +| --- | --- | --- | +| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). | +| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. | + +Both patterns keep the fixed context small and load detail on demand. + +--- + +## Long-Running Agents: Managing Context + +| Pattern | When to use it | What to expect | +| --- | --- | --- | +| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. | +| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. | +| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. | + +**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three. + +--- + +## Caching for Agents + +**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints. + +| Constraint (from `prompt-caching.md`) | Agent-specific workaround | +| --- | --- | +| Editing the system prompt mid-session invalidates the cache. | Append a `` block in the `messages` array instead. The cached prefix stays intact. Claude Code uses this for time updates and mode transitions. | +| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. | +| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. | + +For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns. + +--- + +For live documentation on any of these features, see `live-sources.md`. diff --git a/junie/versions/2206.3/skills/claude-api/shared/error-codes.md b/junie/versions/2206.3/skills/claude-api/shared/error-codes.md new file mode 100644 index 0000000..9d08498 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/error-codes.md @@ -0,0 +1,206 @@ +# HTTP Error Codes Reference + +This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders. + +## Error Code Summary + +| Code | Error Type | Retryable | Common Cause | +| ---- | ----------------------- | --------- | ------------------------------------ | +| 400 | `invalid_request_error` | No | Invalid request format or parameters | +| 401 | `authentication_error` | No | Invalid or missing API key | +| 403 | `permission_error` | No | API key lacks permission | +| 404 | `not_found_error` | No | Invalid endpoint or model ID | +| 413 | `request_too_large` | No | Request exceeds size limits | +| 429 | `rate_limit_error` | Yes | Too many requests | +| 500 | `api_error` | Yes | Anthropic service issue | +| 529 | `overloaded_error` | Yes | API is temporarily overloaded | + +## Detailed Error Information + +### 400 Bad Request + +**Causes:** + +- Malformed JSON in request body +- Missing required parameters (`model`, `max_tokens`, `messages`) +- Invalid parameter types (e.g., string where integer expected) +- Empty messages array +- Messages not alternating user/assistant + +**Example error:** + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "messages: roles must alternate between \"user\" and \"assistant\"" + }, + "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" +} +``` + +**Fix:** Validate request structure before sending. Check that: + +- `model` is a valid model ID +- `max_tokens` is a positive integer +- `messages` array is non-empty and alternates correctly + +--- + +### 401 Unauthorized + +**Causes:** + +- Missing `x-api-key` header or `Authorization` header +- Invalid API key format +- Revoked or deleted API key + +**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly. + +--- + +### 403 Forbidden + +**Causes:** + +- API key doesn't have access to the requested model +- Organization-level restrictions +- Attempting to access beta features without beta access + +**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features. + +--- + +### 404 Not Found + +**Causes:** + +- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`) +- Using deprecated model ID +- Invalid API endpoint + +**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-6`). + +--- + +### 413 Request Too Large + +**Causes:** + +- Request body exceeds maximum size +- Too many tokens in input +- Image data too large + +**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks. + +--- + +### 400 Validation Errors + +Some 400 errors are specifically related to parameter validation: + +- `max_tokens` exceeds model's limit +- Invalid `temperature` value (must be 0.0-1.0) +- `budget_tokens` >= `max_tokens` in extended thinking +- Invalid tool definition schema + +**Common mistake with extended thinking:** + +``` +# Wrong: budget_tokens must be < max_tokens +thinking: budget_tokens=10000, max_tokens=1000 → Error! + +# Correct +thinking: budget_tokens=10000, max_tokens=16000 +``` + +--- + +### 429 Rate Limited + +**Causes:** + +- Exceeded requests per minute (RPM) +- Exceeded tokens per minute (TPM) +- Exceeded tokens per day (TPD) + +**Headers to check:** + +- `retry-after`: Seconds to wait before retrying +- `x-ratelimit-limit-*`: Your limits +- `x-ratelimit-remaining-*`: Remaining quota + +**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples. + +--- + +### 500 Internal Server Error + +**Causes:** + +- Temporary Anthropic service issue +- Bug in API processing + +**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com). + +--- + +### 529 Overloaded + +**Causes:** + +- High API demand +- Service capacity reached + +**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing. + +--- + +## Common Mistakes and Fixes + +| Mistake | Error | Fix | +| ------------------------------- | ---------------- | ------------------------------------------------------- | +| `budget_tokens` >= `max_tokens` | 400 | Ensure `budget_tokens` < `max_tokens` | +| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-6` | +| First message is `assistant` | 400 | First message must be `user` | +| Consecutive same-role messages | 400 | Alternate `user` and `assistant` | +| API key in code | 401 (leaked key) | Use environment variable | +| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` | + +## Typed Exceptions in SDKs + +**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class: + +| HTTP Code | TypeScript Class | Python Class | +| --------- | --------------------------------- | --------------------------------- | +| 400 | `Anthropic.BadRequestError` | `anthropic.BadRequestError` | +| 401 | `Anthropic.AuthenticationError` | `anthropic.AuthenticationError` | +| 403 | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` | +| 404 | `Anthropic.NotFoundError` | `anthropic.NotFoundError` | +| 429 | `Anthropic.RateLimitError` | `anthropic.RateLimitError` | +| 500+ | `Anthropic.InternalServerError` | `anthropic.InternalServerError` | +| Any | `Anthropic.APIError` | `anthropic.APIError` | + +```typescript +// ✅ Correct: use typed exceptions +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.RateLimitError) { + // Handle rate limiting + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} + +// ❌ Wrong: don't check error messages with string matching +try { + const response = await client.messages.create({...}); +} catch (error) { + const msg = error instanceof Error ? error.message : String(error); + if (msg.includes("429") || msg.includes("rate_limit")) { ... } +} +``` + +All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`). diff --git a/junie/versions/2206.3/skills/claude-api/shared/live-sources.md b/junie/versions/2206.3/skills/claude-api/shared/live-sources.md new file mode 100644 index 0000000..343e9d7 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/live-sources.md @@ -0,0 +1,131 @@ +# Live Documentation Sources + +This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated. + +## When to Use WebFetch + +- User explicitly asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered in cached content +- User needs specific API details or examples + +## Claude API Documentation URLs + +### Models & Pricing + +| Topic | URL | Extraction Prompt | +| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" | +| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" | + +### Core Features + +| Topic | URL | Extraction Prompt | +| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" | +| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.6 usage examples" | +| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" | +| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" | +| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" | +| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" | + +### Media & Files + +| Topic | URL | Extraction Prompt | +| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" | +| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" | + +### API Operations + +| Topic | URL | Extraction Prompt | +| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" | +| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" | +| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" | +| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" | +| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" | + +### Tools + +| Topic | URL | Extraction Prompt | +| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" | +| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" | +| Bash Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md` | "Extract bash tool schema, reference implementation, and security considerations" | +| Text Editor | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md` | "Extract text editor tool commands, schema, and reference implementation" | +| Memory Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` | "Extract memory tool commands, directory structure, and implementation patterns" | +| Tool Search | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md` | "Extract tool search setup, when to use, and cache interaction" | +| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code" | +| Skills | `https://platform.claude.com/docs/en/agents-and-tools/skills.md` | "Extract skill folder structure, SKILL.md format, and loading behavior" | + +### Advanced Features + +| Topic | URL | Extraction Prompt | +| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- | +| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" | +| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" | +| Context Editing | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md` | "Extract context editing thresholds, what gets cleared, and configuration" | +| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" | +| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" | + +### Managed Agents + +Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`. + +| Topic | URL | Extraction Prompt | +| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Overview | `https://platform.claude.com/docs/en/managed-agents/overview.md` | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" | +| Quickstart | `https://platform.claude.com/docs/en/managed-agents/quickstart.md` | "Extract the minimal end-to-end agent → environment → session → stream code path" | +| Agent Setup | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md` | "Extract agent create/update/list-versions/archive lifecycle and parameters" | +| Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" | +| Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" | +| Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" | +| Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" | +| Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" | +| Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" | +| Permission Policies | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md` | "Extract permission policy types (allow/deny/confirm) and per-tool config" | +| Multi-Agent | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff" | +| Observability | `https://platform.claude.com/docs/en/managed-agents/observability.md` | "Extract logging, tracing, and usage telemetry exposed by managed agents" | +| GitHub | `https://platform.claude.com/docs/en/managed-agents/github.md` | "Extract github_repository resource shape, multi-repo mounting, and token rotation" | +| MCP Connector | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md` | "Extract MCP server declaration on agents and vault-based credential injection at session" | +| Vaults | `https://platform.claude.com/docs/en/managed-agents/vaults.md` | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive" | +| Skills | `https://platform.claude.com/docs/en/managed-agents/skills.md` | "Extract skill packaging and loading model for managed agents" | +| Memory | `https://platform.claude.com/docs/en/managed-agents/memory.md` | "Extract memory resource shape, scoping, and lifecycle" | +| Onboarding | `https://platform.claude.com/docs/en/managed-agents/onboarding.md` | "Extract first-run setup, prerequisites, and account/region requirements" | +| Cloud Containers | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md` | "Extract cloud container runtime, image config, and network/storage knobs" | +| Migration | `https://platform.claude.com/docs/en/managed-agents/migration.md` | "Extract migration paths from earlier APIs/preview shapes to GA managed agents" | + +### Anthropic CLI + +The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively. + +| Topic | URL | Extraction Prompt | +| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md` | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" | + +--- + +## Claude API SDK Repositories + +WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language. + +| SDK | URL | Extraction Prompt | +| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| Python | `https://github.com/anthropics/anthropic-sdk-python` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| Java | `https://github.com/anthropics/anthropic-sdk-java` | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" | +| Go | `https://github.com/anthropics/anthropic-sdk-go` | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)" | +| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)" | +| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)" | +| PHP | `https://github.com/anthropics/anthropic-sdk-php` | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)" | + +--- + +## Fallback Strategy + +If WebFetch fails (network issues, URL changed): + +1. Use cached content from the language-specific files (note the cache date) +2. Inform user the data may be outdated +3. Suggest they check platform.claude.com or the GitHub repos directly diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-api-reference.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-api-reference.md new file mode 100644 index 0000000..155c877 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-api-reference.md @@ -0,0 +1,299 @@ +# Managed Agents — Endpoint Reference + +All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header. + +## Beta Headers + +``` +anthropic-beta: managed-agents-2026-04-01 +``` + +The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`. + +--- + +## SDK Method Reference + +All resources are under the `beta` namespace. Python and TypeScript share identical method names. + +| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) | +| --- | --- | --- | +| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` | +| Agent Versions | `agents.versions.list` | `Agents.Versions.List` | +| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` | +| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` | +| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | + +**Naming quirks to watch for:** +- Agents have **no delete** — only `archive`. Other resources have both. +- Session resources use `add` (not `create`). +- Go's event stream is `StreamEvents` (not `Stream`). + +**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`). + +**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-6"` — uses `standard` speed) or the full config object (`{type: "model_config", id: "claude-opus-4-6", speed: "fast"}`). + +--- + +## Agents + +**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/agents` | ListAgents | List agents | +| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration | +| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details | +| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration | +| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent (no hard delete for agents) | +| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions | + +## Sessions + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) | +| `POST` | `/v1/sessions` | CreateSession | Create a new session | +| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details | +| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title | +| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session | +| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session | + +## Events + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) | +| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) | +| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE | + +## Session Resources + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session | +| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach file or github_repository mount (SDK method: `add`, not `create`) | +| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource | +| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource | +| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session | + +## Environments + +| Method | Path | Operation | Description | +| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- | +| `POST` | `/v1/environments` | CreateEnvironment | Create environment | +| `GET` | `/v1/environments` | ListEnvironments | List environments | +| `GET` | `/v1/environments/{environment_id}` | GetEnvironment | Get environment details | +| `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment | +| `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. | +| `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment (read-only; existing sessions continue) | + +## Vaults + +Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/vaults` | CreateVault | Create a vault | +| `GET` | `/v1/vaults` | ListVaults | List vaults | +| `GET` | `/v1/vaults/{vault_id}` | GetVault | Get vault details | +| `POST` | `/v1/vaults/{vault_id}` | UpdateVault | Update vault | +| `DELETE` | `/v1/vaults/{vault_id}` | DeleteVault | Delete vault | +| `POST` | `/v1/vaults/{vault_id}/archive` | ArchiveVault | Archive vault | + +## Credentials + +Credentials are individual secrets stored inside a vault. + +| Method | Path | Operation | Description | +| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/vaults/{vault_id}/credentials` | CreateCredential | Create a credential | +| `GET` | `/v1/vaults/{vault_id}/credentials` | ListCredentials | List credentials in vault | +| `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | GetCredential | Get credential metadata | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | UpdateCredential | Update credential | +| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | DeleteCredential | Delete credential | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | ArchiveCredential | Archive credential | + +## Files + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/files` | UploadFile | Upload a file | +| `GET` | `/v1/files` | ListFiles | List files | +| `GET` | `/v1/files/{file_id}` | GetFile | Get file metadata (SDK method: `retrieve_metadata`) | +| `GET` | `/v1/files/{file_id}/content` | DownloadFile | Download file content | +| `DELETE` | `/v1/files/{file_id}` | DeleteFile | Delete a file | + +## Skills + +| Method | Path | Operation | Description | +| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/skills` | CreateSkill | Create a skill | +| `GET` | `/v1/skills` | ListSkills | List skills | +| `GET` | `/v1/skills/{skill_id}` | GetSkill | Get skill details | +| `DELETE` | `/v1/skills/{skill_id}` | DeleteSkill | Delete a skill | +| `POST` | `/v1/skills/{skill_id}/versions` | CreateVersion | Create skill version | +| `GET` | `/v1/skills/{skill_id}/versions` | ListVersions | List skill versions | +| `GET` | `/v1/skills/{skill_id}/versions/{version}` | GetVersion | Get skill version | +| `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | DeleteVersion | Delete skill version | + +--- + +## Request/Response Schema Quick Reference + +### CreateAgent Request Body + +**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session. + +```json +{ + "name": "string (required, 1-256 chars)", + "model": "claude-opus-4-6 (required — bare string, or {id, speed} object)", + "description": "string (optional, up to 2048 chars)", + "system": "string (optional, up to 100,000 chars)", + "tools": [ + { "type": "agent_toolset_20260401" } + ], + "skills": [ + { "type": "anthropic", "skill_id": "xlsx" }, + { "type": "custom", "skill_id": "skill_abc123", "version": "1" } + ], + "mcp_servers": [ + { + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/" + } + ], + "metadata": { + "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)" + } +} +``` + +> Limits: `tools` max 50, `skills` max 64, `mcp_servers` max 20 (unique names). + +### CreateSession Request Body + +```json +{ + "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)", + "environment_id": "env_abc123 (required)", + "title": "string (optional)", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo (required)", + "authorization_token": "ghp_... (required)", + "mount_path": "/workspace/repo (optional — defaults to /workspace/)", + "checkout": { "type": "branch", "name": "main" } + } + ], + "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"], + "metadata": { + "key": "value" + } +} +``` + +> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here. +> +> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch. + +### CreateEnvironment Request Body + +```json +{ + "name": "string (required)", + "description": "string (optional)", + "config": { + "type": "cloud", + "networking": { + "type": "unrestricted | limited (union — see SDK types)" + }, + "packages": { } + }, + "metadata": { "key": "value" } +} +``` + +### SendEvents Request Body + +```json +{ + "events": [ + { + "type": "user.message", + "content": [ + { + "type": "text", + "text": "Hello" + } + ] + } + ] +} +``` + +### Tool Result Event + +```json +{ + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "Result data" }], + "is_error": false +} +``` + +--- + +## Error Handling + +Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`: + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "Description of what went wrong" + }, + "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE" +} +``` + +Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following: + +| Status | Error type | Description | +|---|---|---| +| 400 | `invalid_request_error` | The request was malformed or missing required parameters | +| 401 | `authentication_error` | Invalid or missing API key | +| 403 | `permission_error` | The API key doesn't have permission for this operation | +| 404 | `not_found_error` | The requested resource doesn't exist | +| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) | +| 413 | `request_too_large` | The request body exceeds the maximum allowed size | +| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing | +| 500 | `api_error` | An internal server error occurred | +| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff | + +Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests. + +--- + +## Rate Limits + +Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits. + +| Endpoint group | Scope | RPM | Max concurrent | +|---|---|---|---| +| Create operations (Agents, Sessions, Vaults) | organization | 60 | — | +| All other operations (Agents, Sessions, Vaults) | organization | 600 | — | +| All operations (Environments) | organization | 60 | 5 | + +Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits). + +When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically. diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-client-patterns.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-client-patterns.md new file mode 100644 index 0000000..784a601 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-client-patterns.md @@ -0,0 +1,205 @@ +# Managed Agents — Common Client Patterns + +Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples. + +Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents. + +--- + +## 1. Lossless stream reconnect + +**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between. + +**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up. + +```ts +const seenEventIds = new Set() +const stream = await client.beta.sessions.events.stream(session.id) + +// Stream is now open and buffering server-side. Read history first. +for await (const event of client.beta.sessions.events.list(session.id)) { + seenEventIds.add(event.id) + handle(event) +} + +// Tail the live stream. Dedupe only gates handle() — terminal checks must run +// even for already-seen events, or a terminal event that was in the history +// response gets skipped by `continue` and the loop never exits. +for await (const event of stream) { + if (!seenEventIds.has(event.id)) { + seenEventIds.add(event.id) + handle(event) + } + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break +} +``` + +--- + +## 2. `processed_at` — queued vs processed + +Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp. + +```ts +for await (const event of stream) { + if (event.type === 'user.message') { + if (event.processed_at == null) onQueued(event.id) + else onProcessed(event.id, event.processed_at) + } +} +``` + +Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering). + +--- + +## 3. Interrupt a running session + +Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle. + +```ts +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.interrupt' }], +}) + +// Drain until the session is truly done — see Pattern 5 for the full gate. +for await (const event of stream) { + if (event.type === 'session.status_terminated') break + if ( + event.type === 'session.status_idle' && + event.stop_reason.type !== 'requires_action' + ) break +} +``` + +Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`. + +--- + +## 4. `tool_confirmation` round-trip + +When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`. + +```ts +for await (const event of stream) { + if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') { + await client.beta.sessions.events.send(session.id, { + events: [{ + type: 'user.tool_confirmation', + tool_use_id: event.id, // not a toolu_ id — use event.id + result: 'allow', // or 'deny' + // deny_message: '...', // optional, only with result: 'deny' + }], + }) + } +} +``` + +Key points: +- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID. +- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent. +- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`. + +Reference: `tool-permissions.ts`. + +--- + +## 5. Correct idle-break gate + +Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`. + +```ts +for await (const event of stream) { + handle(event) + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle') { + if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it + break // end_turn or retries_exhausted — both terminal + } +} +``` + +`stop_reason.type` values on `session.status_idle`: +- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break. +- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state. +- `end_turn` — normal completion. + +--- + +## 6. Post-idle status-write race + +The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running." + +Poll before cleanup: + +```ts +let s +for (let i = 0; i < 10; i++) { + s = await client.beta.sessions.retrieve(session.id) + if (s.status !== 'running') break + await new Promise(r => setTimeout(r, 200)) +} +if (s?.status !== 'running') { + await client.beta.sessions.archive(session.id) +} // else: still running after 2s — don't archive, let it settle or escalate +``` + +--- + +## 7. Stream-first, then send + +Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them. + +```ts +const stream = await client.beta.sessions.events.stream(session.id) +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }], +}) +for await (const event of stream) { /* ... */ } +``` + +The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened. + +--- + +## 8. File-mount gotchas + +**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy. + +```ts +const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' }) +// uploaded.id → the original file +const session = await client.beta.sessions.create({ + /* ... */ + resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }], +}) +// session.resources[0].file_id !== uploaded.id ← different IDs +``` + +Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`. + +--- + +## 9. Keep credentials host-side via custom tools + +**Problem:** putting a third-party API key in the agent's vault or environment means the sandbox holds the secret. For keys tied to a human (Linear personal keys, `gh` CLI auth) or keys you'd rather not ship into a container, that's undesirable. + +**Solution:** expose the operation as a custom tool. The agent emits `agent.custom_tool_use`; your orchestrator executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key. + +```ts +// Agent template: declare the tool, no credentials +tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }] + +// Orchestrator: handle the call with host-side creds +for await (const event of stream) { + if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') { + const result = await linear.request(event.input.query, event.input.vars) // host's key + await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }], + }) + } +} +``` + +Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-only auth or binaries. diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-core.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-core.md new file mode 100644 index 0000000..2eb1e47 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-core.md @@ -0,0 +1,216 @@ +# Managed Agents — Core Concepts + +## Architecture + +Managed Agents is built around four core concepts: + +| Concept | Endpoint | What it is | +|---|---|---| +| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. | +| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. | +| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. | +| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. | + +``` + ┌─────────────────────────────────────┐ + │ Anthropic orchestration layer │ +Agent (config) ───────▶│ (agent loop: Claude + tool calls) │ + └──────────────┬──────────────────────┘ + │ tool calls + ▼ +Environment (template) ──▶ Container (tool execution workspace) + │ + Session ─┤ + ├── Resources (files, repos — mounted at startup) + ├── Vault IDs (MCP credential references) + └── Conversation (event stream in/out) +``` + +> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`. + +--- + +## Session Lifecycle + +``` +rescheduling → running ↔ idle → terminated +``` + +| Status | Description | +| -------------- | ------------------------------------------------------------------ | +| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `running` | Session has starting running, and the Agent is actively doing work. | +| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `terminated` | Session has terminated, entering an irreversible and unusable state. | + +- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order. +- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done. +- Errors surface as `session.error` events in the stream, not as a status value. + +### Built-in session features + +- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going +- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost +- **Extended thinking** — on by default, returned as `agent.thinking` events + +### Session operations + +| Operation | Notes | +|---|---| +| List / fetch | Paginated list or single resource by ID | +| Update | Only `title` is updatable | +| Archive | Session becomes **read-only**. Not reversible. | +| Delete | Permanently deletes session, event history, container, and checkpoints. | + +--- + +## Sessions + +A session is a running agent instance inside an environment. + +### Session Object + +Key fields returned by the API: + +| Field | Type | Description | +| --------------- | -------- | --------------------------------------------------- | +| `type` | string | Always `"session"` | +| `id` | string | Unique session ID | +| `title` | string | Human-readable title | +| `status` | string | `idle`, `running`, `rescheduling`, `terminated` | +| `created_at` | string | ISO 8601 timestamp | +| `updated_at` | string | ISO 8601 timestamp | +| `archived_at` | string | ISO 8601 timestamp (nullable) | +| `environment_id` | string | Environment ID | +| `agent` | object | Agent configuration | +| `resources` | array | Attached files and repos | +| `metadata` | object | User-provided key-value pairs (max 8 keys) | +| `usage` | object | Token usage statistics | + +### Creating a session + +**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it: + +```ts +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + system: "You are a helpful coding agent.", + tools: [{ type: "agent_toolset_20260401"}], + }, +); + +// 2. Start a session that references it +const session = await client.beta.sessions.create( + { + agent: agent.id, // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version } + environment_id: environmentId, + title: "Hello World Session", + }, +); +``` + +**Session creation parameters:** + +| Field | Type | Required | Description | +| --------------- | -------- | -------- | ---------------------------------------------- | +| `agent` | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` | +| `environment_id`| string | **Yes** | Environment ID | +| `title` | string | No | Human-readable name (appears in logs/dashboards) | +| `resources` | array | No | Files or GitHub repos, mounted to the container at startup | +| `vault_ids` | array | No | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. | +| `metadata` | object | No | User-provided key-value pairs | + +**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`): + +| Field | Type | Required | Description | +| ------------- | -------- | -------- | ---------------------------------------------- | +| `name` | string | **Yes** | Human-readable name (1-256 chars) | +| `model` | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. | +| `system` | string | No | System prompt — defines the agent's behavior (up to 100K chars) | +| `tools` | array | No | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. | +| `mcp_servers` | array | No | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. | +| `skills` | array | No | Customized "best-practices" context with progressive disclosure. Max 64. See `shared/managed-agents-tools.md` → Skills. | +| `description` | string | No | Description of the agent (up to 2048 chars) | +| `metadata` | object | No | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) | + +--- + +## Agents + +**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session. + +### Agent Object + +The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object. + +| Field | Type | Required | Description | +| ------------------ | -------- | -------- | -------------------------------------------------- | +| `name` | string | Yes | Human-readable name | +| `model` | string | Yes | Claude model ID | +| `system` | string | No | System prompt | +| `tools` | array | No | Agent toolset / MCP toolset / custom tools | +| `mcp_servers` | array | No | MCP server connections | +| `skills` | array | No | Skill references (max 64) | +| `description` | string | No | Description of the agent | +| `metadata` | object | No | Arbitrary key-value pairs | + +### Lifecycle: create once, run many, update in place + +The agent is a **persistent resource**, not a per-run parameter. The intended pattern: + +``` +┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐ +│ agents.create() │ │ sessions.create( │ +│ → store agent_id │ ──→ │ agent={type:..., id: ID} │ +│ in config/env/db │ │ ) │ +└────────────────────────┘ └──────────────────────────────┘ +``` + +**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID. + +### Versioning + +Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version. + +**Why version:** +- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}` +- **Safe iteration** — update the agent without breaking sessions already running on the old version +- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug + +**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility. + +**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`. + +**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update. + +### Agent Endpoints + +| Operation | Method | Path | +| ---------------- | -------- | ------------------------------------- | +| Create | `POST` | `/v1/agents` | +| List | `GET` | `/v1/agents` | +| Get | `GET` | `/v1/agents/{id}` | +| Update | `POST` | `/v1/agents/{id}` | +| Archive | `POST` | `/v1/agents/{id}/archive` | + +### Using an Agent in a Session + +Reference the agent by string ID (latest version) or by object with an explicit version: + +```python +# String shorthand — uses the agent's latest version +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment_id, +) + +# Or pin to a specific version (int) +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment_id, +) +``` + diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-environments.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-environments.md new file mode 100644 index 0000000..64cfefd --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-environments.md @@ -0,0 +1,202 @@ +# Managed Agents — Environments & Resources + +## Environments + +Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration. + +**Environment names must be unique.** Creating an environment with an existing name returns 409. + +### Networking + +| Network Policy | Description | +| ------------------------------- | ------------------------------------------------------------- | +| `unrestricted` | Full egress (except legal blocklist) | +| `package_managers_and_custom` | Package managers + custom `allowed_hosts` | + +```json +{ + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } +} +``` + +**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail. + +### Creating an environment + +The SDK adds `managed-agents-2026-04-01` automatically. TypeScript: + +```ts +const env = await client.beta.environments.create({ + name: "my_env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, +}); +``` + +### Environment CRUD + +| Operation | Method | Path | Notes | +| ---------------- | -------- | ------------------------------------------ | ----- | +| Create | `POST` | `/v1/environments` | | +| List | `GET` | `/v1/environments` | Paginated (`limit`, `after_id`, `before_id`) | +| Get | `GET` | `/v1/environments/{id}` | | +| Update | `POST` | `/v1/environments/{id}` | Changes apply only to **new** containers; existing sessions keep their original config | +| Delete | `DELETE` | `/v1/environments/{id}` | Returns 204. | +| Archive | `POST` | `/v1/environments/{id}/archive` | Read-only. New sessions can't be created; existing ones continue. | + +--- + +## Resources + +Attach files and GitHub repositories to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. + +### File Uploads (input — host → agent) + +Upload a file first via the Files API, then reference by `file_id` + `mount_path`: + +```ts +// 1. Upload +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// 2. Attach as a session resource +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + resources: [ + { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" } + ], +}); +``` + +**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths. + +### Session outputs (output — agent → host) + +The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards: + +```ts +// After the turn completes, list output files scoped to this session: +for await (const f of client.beta.files.list({ scope: session.id })) { + console.log(f.filename, f.size_bytes); + const resp = await client.beta.files.download(f.id); + const text = await resp.text(); +} +``` + +**Requirements:** +- The `write` tool (or `bash`) must be enabled for the agent to create output files. +- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`. +- `session_id` is a query filter on `files.list` (not yet in SDK types — cast or spread through). +- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty. + +This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out. + +### GitHub Repositories + +Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. + +**Fields:** + +| Field | Required | Notes | +|---|---|---| +| `type` | ✅ | `"github_repository"` | +| `url` | ✅ | The GitHub repository URL | +| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** | +| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/`. | +| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. | + +**Token permission levels** (fine-grained PATs): +- `Contents: Read` — clone only +- `Contents: Read and write` — push changes and create pull requests + +> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` → create PR via MCP `create_pull_request` tool. + +**TypeScript:** + +```ts +// 1. Create the agent — declare GitHub MCP (no auth here) +const agent = await client.beta.agents.create( + { + name: 'GitHub Agent', + model: 'claude-opus-4-6', + mcp_servers: [ + { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' }, + ], + tools: [ + { type: 'agent_toolset_20260401', default_config: { enabled: true } }, + { type: 'mcp_toolset', mcp_server_name: 'github' }, + ], + }, +); + +// 2. Start a session — attach vault for MCP auth + mount the repo +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential + resources: [ + { + type: 'github_repository', + url: 'https://github.com/owner/repo', + authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth) + checkout: { type: 'branch', name: 'main' }, + }, + ], +}); +``` + +**Python:** + +```python +import os + +agent = client.beta.agents.create( + name="GitHub Agent", + model="claude-opus-4-6", + mcp_servers=[{ + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/", + }], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "github"}, + ], +) + +session = client.beta.sessions.create( + agent=agent.id, + environment_id=env_id, + vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential + resources=[{ + "type": "github_repository", + "url": "https://github.com/owner/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth) + "checkout": {"type": "branch", "name": "main"}, + }], +) +``` + +--- + +## Files API + +Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`. + +| Operation | Method | Path | SDK | +| ---------------- | -------- | ------------------------------------- | --- | +| Upload | `POST` | `/v1/files` | `client.beta.files.upload({ file })` | +| List | `GET` | `/v1/files?session_id=...` | `client.beta.files.list({ session_id })` | +| Get Metadata | `GET` | `/v1/files/{id}` | `client.beta.files.retrieveMetadata(id)` | +| Download | `GET` | `/v1/files/{id}/content` | `client.beta.files.download(id)` → `Response` | +| Delete | `DELETE` | `/v1/files/{id}` | `client.beta.files.delete(id)` | + +The `session_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account. diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-events.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-events.md new file mode 100644 index 0000000..5b10581 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-events.md @@ -0,0 +1,187 @@ +# Managed Agents — Events & Steering + +## Events + +### Sending Events + +Send events to a session via `POST /v1/sessions/{id}/events`. + +| Event Type | When to Send | +| ------------------------- | --------------------------------------------------- | +| `user.message` | Send a user message | +| `user.interrupt` | Interrupt the agent while it's running | +| `user.tool_confirmation` | Approve/deny a tool call (when `always_ask` policy) | +| `user.custom_tool_result` | Provide result for a custom tool call | + +### Receiving Events + +Two methods: + +1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive. +2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll. + +All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent). + +> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely. +> +> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem. + +### Event Types (Received) + +Event types use dot notation, grouped by namespace: + +| Event Type | Description | +| --- | --- | +| `agent.message` | Agent text output | +| `agent.thinking` | Extended thinking blocks | +| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) | +| `agent.tool_result` | Result from a built-in tool | +| `agent.mcp_tool_use` | Agent used an MCP tool | +| `agent.mcp_tool_result` | Result from an MCP tool | +| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` | +| `agent.thread_context_compacted` | Conversation context was compacted | +| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `session.status_running` | Session has starting running, and the Agent is actively doing work. | +| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state. | +| `session.error` | Error occurred during processing | +| `span.model_request_start` | Model inference started | +| `span.model_request_end` | Model inference completed | + +The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`). + +--- + +## Steering Patterns + +Practical patterns for driving a session via the events surface. + +### Stream-first ordering + +**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time. + +```ts +// ✅ Correct — stream and send concurrently +const [response] = await Promise.all([ + streamEvents(sessionId), // opens SSE connection + sendMessage(sessionId, text), +]); + +// ❌ Wrong — events before stream opens arrive as a single buffered batch +await sendMessage(sessionId, text); +const response = await streamEvents(sessionId); +``` + +**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward. + +### Reconnecting after a dropped stream + +**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream. + +**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID: + +```python +def connect_with_consolidation(client, session_id): + # 1. Open the SSE stream first + stream = client.beta.sessions.events.stream(session_id=session_id) + + # 2. Fetch history to cover any gap + history = client.beta.sessions.events.list( + session_id=session_id, + ) + + # 3. Yield history first, then stream — dedupe by event.id + seen = set() + for ev in history.data: + seen.add(ev.id) + yield ev + for ev in stream: + if ev.id not in seen: + seen.add(ev.id) + yield ev +``` + +### Message queuing + +**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups: + +```ts +// All three go into one session; agent processes them in order +await sendMessage(sessionId, "Summarize the README"); +await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide"); +await sendMessage(sessionId, "And compare the two"); +// Stream once — agent responds to all three as a coherent turn +``` + +Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()` + +### Interrupt + +An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands: + +```ts +await client.beta.sessions.events.send(sessionId, { + events: [{ type: 'interrupt' }], +}); +``` + +The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. + +> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs. + +### Event payloads + +some events carry useful metadata beyond the status change itself: + +`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user. +```json +{ + "id": "sevt_456", + "processed_at": "2026-04-07T04:27:43.197Z", + "stop_reason": { + "event_ids": [ + "sevt_123" + ], + "type": "requires_action" + }, + "type": "status_idle" +} +``` + +`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis: + +```json +{ + "type": "span.model_request_end", + "id": "sevt_456", + "is_error": false, + "model_request_start_id": "sevt_123", + "model_usage": { + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 6656, + "input_tokens": 3571, + "output_tokens": 727 + }, + "processed_at": "2026-04-07T04:11:32.189Z" +} +``` + +**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed: + +```json +{ + "id": "sevt_abc123", + "processed_at": "2026-03-24T14:05:15.787Z", + "type": "agent.thread_context_compacted" +} +``` + +### Archive + +When done with a session, archive it to free resources: + +```ts +await client.beta.sessions.archive(sessionId); +``` + + diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-onboarding.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-onboarding.md new file mode 100644 index 0000000..9ee9501 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-onboarding.md @@ -0,0 +1,114 @@ +# Managed Agents — Onboarding Flow + +> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions. + +Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code. + +> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference. + +--- + +Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you. + +**What you supply:** +- **An agent config** — tools, skills, model, system prompt. Reusable and versioned. +- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents. + +Each run of the agent is a **session**. + +--- + +## 1. Know or explore? + +Ask the user: + +> Do you already know the agent you want to build, or would you like to explore some common patterns first? + +### Explore path — show the patterns + +Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ. + +| Pattern | Trigger | Example | +|---|---|---| +| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete? +| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete? +| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI | +| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard | + +Ask which shape fits, then continue with the Know path using it as the reference. + +### Know path — configure template + +Three rounds. Batch the questions in each round; don't ask them one at a time. + +**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination): + +| Type | What it is | How to guide | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. | +| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. | +| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. | + +**Round B — Skills, files, and repos.** What the agent has on hand when it starts. + +*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 64 per agent. +- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name. +- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API. + +*GitHub repositories* — any repos the agent needs on-disk? For each: +- [ ] Repo URL (`https://github.com/org/repo`) +- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo) +- [ ] Optional `mount_path` (defaults to `/workspace/`) and `checkout` (branch or SHA) + +Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories. + +> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool. + +*Files* — any local files to seed the session with? For each: +- [ ] Upload via the Files API → persist `file_id` +- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only) + +Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API. + +**Round C — Environment + identity:** +- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.) +- [ ] Name? +- [ ] Job (one or two sentences — becomes the system prompt)? +- [ ] Model? (default `claude-opus-4-6`) + +--- + +## 2. Set up the session + +Per-run. Points at the agent + environment, attaches credentials, kicks off. + +**Vault credentials** (if the agent declared MCP servers): +- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`) + +Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults. + +**Kickoff:** +- [ ] First message to the agent? + +Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope: session_id})`. + +--- + +## 3. Emit the code + +Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection): + +**Block 1 — Setup (run once, store the IDs):** +1. `environments.create()` → persist `env_id` +2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version` + +Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env` + +**Block 2 — Runtime (run on every invocation):** +1. Load `env_id` + `agent_id` from config/env +2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])` +3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`) + +> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`. + +Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names. diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-overview.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-overview.md new file mode 100644 index 0000000..bbb0a89 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-overview.md @@ -0,0 +1,61 @@ +# Managed Agents — Overview + +Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in. + +## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run) + +**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run. + +Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs. + +| Step | Call | Frequency | +|---|---|---| +| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. | +| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. | + +If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only. + +**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`. + +**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. + +## Beta Headers + +Managed Agents is in beta. The SDK sets required beta headers automatically: + +| Beta Header | What it enables | +| ------------------------------ | ---------------------------------------------------- | +| `managed-agents-2026-04-01` | Agents, Environments, Sessions, Events, Session Resources, Vaults, Credentials | +| `skills-2025-10-02` | Skills API (for managing custom skill definitions) | +| `files-api-2025-04-14` | Files API for file uploads | + +**Note: do not intermix beta headers** — If you need to upload a skill or file via the Skills API or Files API you will need to use the appropriate beta header as listed above. However, you do NOT need to inlude either the Skills or Files beta header when using any of the Managed Agents endpints listed in row 1 above. Do NOT include intermix beta headers and prefer to use the Skills or Files beta headers when using their specific endpoints. + + +## Reading Guide + +| User wants to... | Read these files | +| -------------------------------------- | ------------------------------------------------------- | +| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code | +| Understand how the API works | `shared/managed-agents-core.md` | +| See the full endpoint reference | `shared/managed-agents-api-reference.md` | +| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file | +| Update/version an agent | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create | +| Create a session | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` | +| Configure tools and permissions | `shared/managed-agents-tools.md` | +| Set up MCP servers | `shared/managed-agents-tools.md` (MCP Servers section) | +| Stream events / handle tool_use | `shared/managed-agents-events.md` + language file | +| Set up environments | `shared/managed-agents-environments.md` + language file | +| Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) | +| Store MCP credentials | `shared/managed-agents-tools.md` (Vaults section) | + +## Common Pitfalls + +- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example. +- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility. +- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token. +- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time. +- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream. +- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. +- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message. +- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type. diff --git a/junie/versions/2206.3/skills/claude-api/shared/managed-agents-tools.md b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-tools.md new file mode 100644 index 0000000..cce75c9 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/managed-agents-tools.md @@ -0,0 +1,301 @@ +# Managed Agents — Tools & Skills + +## Tools + +### Server tools vs client tools + +| Type | Who runs it | How it works | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. | +| **MCP tools** (`mcp_toolset`) | Anthropic, on the session's container | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. | +| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. | + +**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed. + +**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting. + +### Agent Toolset + +The `agent_toolset_20260401` provides these built-in tools: + +| Tool | Description | +| ---------------------- | ---------------------------------------- | +| `bash` | Execute bash commands in a shell session | +| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks | +| `write` | Write a file to the local filesystem | +| `edit` | Perform string replacement in a file | +| `glob` | Fast file pattern matching using glob patterns | +| `grep` | Text search using regex patterns | +| `web_fetch` | Fetch content from a URL | +| `web_search` | Search the web for information | + +Enable the full toolset: + +```json +{ + "tools": [ + { "type": "agent_toolset_20260401" } + ] +} +``` + +### Per-Tool Configuration + +Override defaults for individual tools. This example enables everything except bash: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] +} +``` + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"agent_toolset_20260401"` | +| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` | +| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` | + +### Permission Policies + +Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools. + +| Policy | Behavior | +|---|---| +| `always_allow` | Tool executes automatically (default) | +| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event | + +```json +{ + "type": "agent_toolset_20260401", + "default_config": { + "enabled": true, + "permission_policy": { "type": "always_allow" } + }, + "configs": [ + { "name": "bash", "permission_policy": { "type": "always_ask" } } + ] +} +``` + +**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event: + +```json +{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" } +{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" } +``` + +The optional `message` on a deny is delivered to the agent so it can adjust its approach. + +To enable only specific tools, flip the default off and opt-in per tool: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": false }, + "configs": [ + { "name": "bash", "enabled": true }, + { "name": "read", "enabled": true } + ] + } + ] +} +``` + +### Custom Tools (Client-Side) + +Custom tools are executed by **your application**, not Anthropic. The flow: + +1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs +2. Session goes `idle` waiting for you +3. Your application executes the tool +4. You send back a `user.custom_tool_result` event with the output +5. Session resumes `running` + +No permission policy needed — you're the one executing. + +```json +{ + "tools": [ + { + "type": "custom", + "name": "get_weather", + "description": "Fetch current weather for a city.", + "input_schema": { + "type": "object", + "properties": { + "city": { "type": "string", "description": "City name" } + }, + "required": ["city"] + } + } + ] +} +``` + +### MCP Servers + +MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:** + +1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field. +2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create. + +This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL. + +**Agent side — declare servers (no auth):** + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"url"` | +| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` | +| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) | + +```json +{ + "mcp_servers": [ + { "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" } + ], + "tools": [ + { "type": "mcp_toolset", "mcp_server_name": "linear" } + ] +} +``` + +**Session side — attach vault:** + +```json +{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] +} +``` + +> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form. + +> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems. + +### Vaults — the MCP credential store + +**Vaults** store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers in the launch SDK. + +> Formerly known internally as TATs (Tool/Tenant Access Tokens). + +**Flow:** + +1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model +2. Add MCP credentials to it (`client.beta.vaults.credentials.create(...)`) — each credential is tied to one MCP server URL +3. Reference the vault on session create via `vault_ids: ["vlt_..."]` +4. Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools + +**Credential shape**: + +```json +{ + "display_name": "Notion (workspace-foo)", + "auth": { + "type": "mcp_oauth", + "mcp_server_url": "https://mcp.notion.com/mcp", + "access_token": "", + "expires_at": "2026-04-02T14:00:00Z", + "refresh": { + "refresh_token": "", + "client_id": "", + "token_endpoint": "https://api.notion.com/v1/oauth/token", + "token_endpoint_auth": { "type": "none" } + } + } +} +``` + +The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union: + +| `type` | Shape | Use when | +|---|---|---| +| `"none"` | `{type: "none"}` | Public OAuth client (no secret) | +| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth | +| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body | + +Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access. + +> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there. + +**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected"). + +--- + +## Skills + +Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. + +Two types — both work the same way; the agent automatically uses them when relevant to the task at hand: + +| Type | What it is | +|---|---| +| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). | +| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. | + +**Max 64 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`. + +### Enabling skills on a session + +Skills are attached to the **agent** definition via `agents.create()`: + +```ts +const agent = await client.beta.agents.create( + { + name: "Financial Agent", + model: "claude-opus-4-6", + system: "You are a financial analysis agent.", + skills: [ + { type: "anthropic", skill_id: "xlsx" }, + { type: "custom", skill_id: "skill_abc123", version: "latest" }, + ], + } +); +``` + +Python: + +```python +agent = client.beta.agents.create( + name="Financial Agent", + model="claude-opus-4-6", + system="You are a financial analysis agent.", + skills=[ + {"type": "anthropic", "skill_id": "xlsx"}, + {"type": "custom", "skill_id": "skill_abc123", "version": "latest"}, + ] +) +``` + +**Skill reference fields:** + +| Field | Anthropic skill | Custom skill | +|---|---|---| +| `type` | `"anthropic"` | `"custom"` | +| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) | +| `version` | — | `"latest"` or a specific version number | + +### Skills API + +| Operation | Method | Path | +| --------------------- | -------- | ----------------------------------------------- | +| Create Skill | `POST` | `/v1/skills` | +| List Skills | `GET` | `/v1/skills` | +| Get Skill | `GET` | `/v1/skills/{id}` | +| Delete Skill | `DELETE` | `/v1/skills/{id}` | +| Create Version | `POST` | `/v1/skills/{id}/versions` | +| List Versions | `GET` | `/v1/skills/{id}/versions` | +| Get Version | `GET` | `/v1/skills/{id}/versions/{version}` | +| Delete Version | `DELETE` | `/v1/skills/{id}/versions/{version}` | + diff --git a/junie/versions/2206.3/skills/claude-api/shared/models.md b/junie/versions/2206.3/skills/claude-api/shared/models.md new file mode 100644 index 0000000..6344d60 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/models.md @@ -0,0 +1,119 @@ +# Claude Model Catalog + +**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below). + +## Programmatic Model Discovery + +For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime. + +```python +m = client.models.retrieve("claude-opus-4-6") +m.id # "claude-opus-4-6" +m.display_name # "Claude Opus 4.6" +m.max_input_tokens # context window (int) +m.max_tokens # max output tokens (int) + +# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf +caps = m.capabilities +caps["image_input"]["supported"] # vision +caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking +caps["effort"]["max"]["supported"] # effort: max (also low/medium/high) +caps["structured_outputs"]["supported"] +caps["context_management"]["compact_20260112"]["supported"] + +# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data +[m for m in client.models.list() + if m.capabilities["thinking"]["types"]["adaptive"]["supported"] + and m.max_input_tokens >= 200_000] +``` + +Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration. + +### Raw HTTP + +```bash +curl https://api.anthropic.com/v1/models/claude-opus-4-6 \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" +``` + +```json +{ + "id": "claude-opus-4-6", + "display_name": "Claude Opus 4.6", + "max_input_tokens": 1000000, + "max_tokens": 128000, + "capabilities": { + "image_input": {"supported": true}, + "structured_outputs": {"supported": true}, + "thinking": {"supported": true, "types": {"enabled": {"supported": true}, "adaptive": {"supported": true}}}, + "effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}}, + … + } +} +``` + +## Current Models (recommended) + +| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status | +|-------------------|---------------------|-------------------------------|----------------|------------|--------| +| Claude Opus 4.6 | `claude-opus-4-6` | — | 200K (1M beta) | 128K | Active | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 200K (1M beta) | 64K | Active | +| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active | + +### Model Descriptions + +- **Claude Opus 4.6** — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via `context-1m-2025-08-07` header. +- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via `context-1m-2025-08-07` header. 64K max output tokens. +- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks. + +## Legacy Models (still active) + +| Friendly Name | Alias (use this) | Full ID | Status | +|-------------------|---------------------|-------------------------------|--------| +| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active | +| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Active | +| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active | +| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Active | +| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Active | + +## Deprecated Models (retiring soon) + +| Friendly Name | Alias (use this) | Full ID | Status | Retires | +|-------------------|---------------------|-------------------------------|------------|--------------| +| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | Apr 19, 2026 | + +## Retired Models (no longer available) + +| Friendly Name | Full ID | Retired | +|-------------------|-------------------------------|-------------| +| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 | +| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 | +| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 | +| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 | +| Claude 2.1 | `claude-2.1` | Jul 21, 2025 | +| Claude 2.0 | `claude-2.0` | Jul 21, 2025 | + +## Resolving User Requests + +When a user asks for a model by name, use this table to find the correct model ID: + +| User says... | Use this model ID | +|-------------------------------------------|--------------------------------| +| "opus", "most powerful" | `claude-opus-4-6` | +| "opus 4.6" | `claude-opus-4-6` | +| "opus 4.5" | `claude-opus-4-5` | +| "opus 4.1" | `claude-opus-4-1` | +| "opus 4", "opus 4.0" | `claude-opus-4-0` | +| "sonnet", "balanced" | `claude-sonnet-4-6` | +| "sonnet 4.6" | `claude-sonnet-4-6` | +| "sonnet 4.5" | `claude-sonnet-4-5` | +| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` | +| "sonnet 3.7" | Retired — suggest `claude-sonnet-4-5` | +| "sonnet 3.5" | Retired — suggest `claude-sonnet-4-5` | +| "haiku", "fast", "cheap" | `claude-haiku-4-5` | +| "haiku 4.5" | `claude-haiku-4-5` | +| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` | +| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` | diff --git a/junie/versions/2206.3/skills/claude-api/shared/prompt-caching.md b/junie/versions/2206.3/skills/claude-api/shared/prompt-caching.md new file mode 100644 index 0000000..2bd9bca --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/prompt-caching.md @@ -0,0 +1,171 @@ +# Prompt Caching — Design & Optimization + +This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc. + +## The one invariant everything follows from + +**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.** + +The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N. + +Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together. + +Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help. + +--- + +## Workflow for optimizing existing code + +When asked to add or optimize caching: + +1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them. +2. **Classify each input by stability:** + - Never changes → belongs early in the prompt, before any breakpoint + - Changes per-session → belongs after the global prefix, cache per-session + - Changes per-turn → belongs at the end, after the last breakpoint + - Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end** +3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers. +4. **Place breakpoints at stability boundaries.** See placement patterns below. +5. **Audit for silent invalidators.** See anti-patterns table. + +--- + +## Placement patterns + +### Large system prompt shared across many requests + +Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together. + +```json +"system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} +] +``` + +### Multi-turn conversations + +Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows. + +```json +// Last content block of the last user turn +messages[-1].content[-1].cache_control = {"type": "ephemeral"} +``` + +### Shared prefix, varying suffix + +Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read. + +```json +"messages": [{"role": "user", "content": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": ""} // no marker — differs every time +]}] +``` + +### Prompts that change from the beginning every time + +Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off. + +--- + +## Architectural guidance + +These are the decisions that matter more than marker placement. Fix these first. + +**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context as a user or assistant message later in `messages`. A message at turn 5 invalidates nothing before turn 5. + +**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name). + +**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end. + +--- + +## Silent invalidators + +When reviewing code, grep for these inside anything that feeds the prompt prefix: + +| Pattern | Why it breaks caching | +|---|---| +| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request | +| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique | +| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ | +| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing | +| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix | +| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users | + +Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing. + +--- + +## API reference + +```json +"cache_control": {"type": "ephemeral"} // 5-minute TTL (default) +"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL +``` + +- Max **4** `cache_control` breakpoints per request. +- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`). +- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement. +- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`: + +| Model | Minimum | +|---|---:| +| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens | +| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens | +| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens | + +A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.6. + +**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off. + +--- + +## Verifying cache hits + +The response `usage` object reports cache activity: + +| Field | Meaning | +|---|---| +| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) | +| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) | +| `input_tokens` | Tokens processed at full price (not cached) | + +If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it. + +**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field. + +Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java). + +--- + +## Invalidation hierarchy + +Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below: + +| Change | Tools cache | System cache | Messages cache | +|---|:---:|:---:|:---:| +| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ | +| Model switch | ❌ | ❌ | ❌ | +| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ | +| System prompt content | ✅ | ❌ | ❌ | +| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ | +| Message content | ✅ | ✅ | ❌ | + +Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild. + +--- + +## 20-block lookback window + +Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses. + +Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block. + +--- + +## Concurrent-request timing + +A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing. + +For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote. diff --git a/junie/versions/2206.3/skills/claude-api/shared/tool-use-concepts.md b/junie/versions/2206.3/skills/claude-api/shared/tool-use-concepts.md new file mode 100644 index 0000000..65d9637 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/shared/tool-use-concepts.md @@ -0,0 +1,327 @@ +# Tool Use Concepts + +This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`. + +## User-Defined Tools + +### Tool Definition Structure + +> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support. + +Each tool requires a name, description, and JSON Schema for its inputs: + +```json +{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City and state, e.g., San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "Temperature unit" + } + }, + "required": ["location"] + } +} +``` + +**Best practices for tool definitions:** + +- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`) +- Write detailed descriptions — Claude uses these to decide when to use the tool +- Include descriptions for each property +- Use `enum` for parameters with a fixed set of values +- Mark truly required parameters in `required`; make others optional with defaults + +--- + +### Tool Choice Options + +Control when Claude uses tools: + +| Value | Behavior | +| --------------------------------- | --------------------------------------------- | +| `{"type": "auto"}` | Claude decides whether to use tools (default) | +| `{"type": "any"}` | Claude must use at least one tool | +| `{"type": "tool", "name": "..."}` | Claude must use the specified tool | +| `{"type": "none"}` | Claude cannot use tools | + +Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response. + +--- + +### Tool Runner vs Manual Loop + +**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. + +**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`. + +**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically. + +```python +# Handle pause_turn in your agentic loop +if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_query}, + {"role": "assistant", "content": response.content}, + ] + # Make another API request — server resumes automatically + response = client.messages.create( + model="claude-opus-4-6", messages=messages, tools=tools + ) +``` + +Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons` + +> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution. + +--- + +### Handling Tool Results + +When Claude uses a tool, the response contains a `tool_use` block. You must: + +1. Execute the tool with the provided input +2. Send the result back in a `tool_result` message +3. Continue the conversation + +**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification. + +**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message. + +--- + +## Server-Side Tools: Code Execution + +The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest. + +### Key Facts + +- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk) +- No internet access (fully sandboxed) +- Python 3.11 with data science libraries pre-installed +- Containers persist for 30 days and can be reused across requests +- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization + +### Tool Definition + +The tool requires no schema — just declare it in the `tools` array: + +```json +{ + "type": "code_execution_20260120", + "name": "code_execution" +} +``` + +Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files). + +### Pre-installed Python Libraries + +- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels +- **Visualization**: matplotlib, seaborn +- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx +- **Math**: sympy, mpmath +- **Utilities**: tqdm, python-dateutil, pytz, sqlite3 + +Additional packages can be installed at runtime via `pip install`. + +### Supported File Types for Upload + +| Type | Extensions | +| ------ | ---------------------------------- | +| Data | CSV, Excel (.xlsx/.xls), JSON, XML | +| Images | JPEG, PNG, GIF, WebP | +| Text | .txt, .md, .py, .js, etc. | + +### Container Reuse + +Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests. + +### Response Structure + +The response contains interleaved text and tool result blocks: + +- `text` — Claude's explanation +- `server_tool_use` — What Claude is doing +- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure) +- `text_editor_code_execution_tool_result` — File operation results + +> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory. + +--- + +## Server-Side Tools: Web Search and Web Fetch + +Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically. + +### Tool Definitions + +```json +[ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } +] +``` + +### Dynamic Filtering (Opus 4.6 / Sonnet 4.6) + +The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header. + +```json +{ + "tools": [ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } + ] +} +``` + +Without dynamic filtering, the previous `web_search_20250305` version is also available. + +> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model. + +--- + +## Server-Side Tools: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again. + +Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling` + +--- + +## Server-Side Tools: Tool Search + +The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool` + +--- + +## Skills + +Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills` + +--- + +## Tool Use Examples + +You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use` + +--- + +## Server-Side Tools: Computer Use + +Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview` + +--- + +## Context Editing + +Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing` + +--- + +## Client-Side Tools: Memory + +The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions. + +### Key Facts + +- Client-side tool — you control storage via your implementation +- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename` +- Operates on files in a `/memories` directory +- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend + +> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers. + +For full implementation examples, use WebFetch: + +- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` + +--- + +## Structured Outputs + +Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation. + +Two features are available: + +- **JSON outputs** (`output_config.format`): Control Claude's response format +- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas + +**Supported models:** Claude Opus 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. + +> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter. + +### JSON Schema Limitations + +**Supported:** + +- Basic types: object, array, string, integer, number, boolean, null +- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def` +- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` +- `additionalProperties: false` (required for all objects) + +**Not supported:** + +- Recursive schemas +- Numerical constraints (`minimum`, `maximum`, `multipleOf`) +- String constraints (`minLength`, `maxLength`) +- Complex array constraints +- `additionalProperties` set to anything other than `false` + +The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side. + +### Important Notes + +- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache. +- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema. +- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`. +- **Incompatible with**: Citations (returns 400 error), message prefilling. +- **Works with**: Batches API, streaming, token counting, extended thinking. + +--- + +## Tips for Effective Tool Use + +1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools +2. **Use specific tool names**: `get_current_weather` is better than `weather` +3. **Validate inputs**: Always validate tool inputs before execution +4. **Handle errors gracefully**: Return informative error messages so Claude can adapt +5. **Limit tool count**: Too many tools can confuse the model — keep the set focused +6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios + +For detailed tool use documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/claude-api/README.md b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/README.md new file mode 100644 index 0000000..3847621 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/README.md @@ -0,0 +1,333 @@ +# Claude API — TypeScript + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Basic Message Request + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [{ role: "user", content: "What is the capital of France?" }], +}); +// response.content is ContentBlock[] — a discriminated union. Narrow by .type +// before accessing .text (TypeScript will error on content[0].text without this). +for (const block of response.content) { + if (block.type === "text") { + console.log(block.text); + } +} +``` + +--- + +## System Prompts + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: + "You are a helpful coding assistant. Always provide examples in Python.", + messages: [{ role: "user", content: "How do I read a JSON file?" }], +}); +``` + +--- + +## Vision (Images) + +### URL + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "url", url: "https://example.com/image.png" }, + }, + { type: "text", text: "Describe this image" }, + ], + }, + ], +}); +``` + +### Base64 + +```typescript +import fs from "fs"; + +const imageData = fs.readFileSync("image.png").toString("base64"); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "base64", media_type: "image/png", data: imageData }, + }, + { type: "text", text: "What's in this image?" }, + ], + }, + ], +}); +``` + +--- + +## Prompt Caching + +**Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block + system: "You are an expert on this large document...", + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral" }, // default TTL is 5 minutes + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// With explicit TTL (time-to-live) +const response2 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Verifying Cache Hits + +```typescript +console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost) +console.log(response.usage.cache_read_input_tokens); // tokens served from cache (~0.1x cost) +console.log(response.usage.input_tokens); // uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `Date.now()` or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```typescript +// Opus 4.6: adaptive thinking (recommended) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + thinking: { type: "adaptive" }, + output_config: { effort: "high" }, // low | medium | high | max + messages: [ + { role: "user", content: "Solve this math problem step by step..." }, + ], +}); + +for (const block of response.content) { + if (block.type === "thinking") { + console.log("Thinking:", block.thinking); + } else if (block.type === "text") { + console.log("Response:", block.text); + } +} +``` + +--- + +## Error Handling + +Use the SDK's typed exception classes — never check error messages with string matching: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.BadRequestError) { + console.error("Bad request:", error.message); + } else if (error instanceof Anthropic.AuthenticationError) { + console.error("Invalid API key"); + } else if (error instanceof Anthropic.RateLimitError) { + console.error("Rate limited - retry later"); + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} +``` + +All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference. + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array: + +```typescript +const messages: Anthropic.MessageParam[] = [ + { role: "user", content: "My name is Alice." }, + { role: "assistant", content: "Hello Alice! Nice to meet you." }, + { role: "user", content: "What's my name?" }, +]; + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: messages, +}); +``` + +**Rules:** + +- Consecutive same-role messages are allowed — the API combines them into a single turn +- First message must be `user` +- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const messages: Anthropic.Beta.BetaMessageParam[] = []; + +async function chat(userMessage: string): Promise { + messages.push({ role: "user", content: userMessage }); + + const response = await client.beta.messages.create({ + betas: ["compact-2026-01-12"], + model: "claude-opus-4-6", + max_tokens: 16000, + messages, + context_management: { + edits: [{ type: "compact_20260112" }], + }, + }); + + // Append full content — compaction blocks must be preserved + messages.push({ role: "assistant", content: response.content }); + + const textBlock = response.content.find( + (b): b is Anthropic.Beta.BetaTextBlock => b.type === "text", + ); + return textBlock?.text ?? ""; +} + +// Compaction triggers automatically when context grows large +console.log(await chat("Help me build a Python web scraper")); +console.log(await chat("Add support for JavaScript-rendered pages")); +console.log(await chat("Now add rate limiting and error handling")); +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +| --------------- | --------------------------------------------------------------- | +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```typescript +// Automatic caching (simplest — caches the last cacheable block) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, + system: largeDocumentText, // e.g., 50KB of context + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// First request: full cost +// Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Use Token Counting Before Requests + +```typescript +const countResponse = await client.messages.countTokens({ + model: "claude-opus-4-6", + messages: messages, + system: system, +}); + +const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens +console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`); +``` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/claude-api/batches.md b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/batches.md new file mode 100644 index 0000000..e7a9fa3 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/batches.md @@ -0,0 +1,106 @@ +# Message Batches API — TypeScript + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const messageBatch = await client.messages.batches.create({ + requests: [ + { + custom_id: "request-1", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Summarize climate change impacts" }, + ], + }, + }, + { + custom_id: "request-2", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Explain quantum computing basics" }, + ], + }, + }, + ], +}); + +console.log(`Batch ID: ${messageBatch.id}`); +console.log(`Status: ${messageBatch.processing_status}`); +``` + +--- + +## Poll for Completion + +```typescript +let batch; +while (true) { + batch = await client.messages.batches.retrieve(messageBatch.id); + if (batch.processing_status === "ended") break; + console.log( + `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`, + ); + await new Promise((resolve) => setTimeout(resolve, 60_000)); +} + +console.log("Batch complete!"); +console.log(`Succeeded: ${batch.request_counts.succeeded}`); +console.log(`Errored: ${batch.request_counts.errored}`); +``` + +--- + +## Retrieve Results + +```typescript +for await (const result of await client.messages.batches.results( + messageBatch.id, +)) { + switch (result.result.type) { + case "succeeded": + console.log( + `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`, + ); + break; + case "errored": + if (result.result.error.type === "invalid_request") { + console.log(`[${result.custom_id}] Validation error - fix and retry`); + } else { + console.log(`[${result.custom_id}] Server error - safe to retry`); + } + break; + case "expired": + console.log(`[${result.custom_id}] Expired - resubmit`); + break; + } +} +``` + +--- + +## Cancel a Batch + +```typescript +const cancelled = await client.messages.batches.cancel(messageBatch.id); +console.log(`Status: ${cancelled.processing_status}`); // "canceling" +``` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/claude-api/files-api.md b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/files-api.md new file mode 100644 index 0000000..5f1223d --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/files-api.md @@ -0,0 +1,98 @@ +# Files API — TypeScript + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import fs from "fs"; + +const client = new Anthropic(); + +const uploaded = await client.beta.files.upload({ + file: await toFile(fs.createReadStream("report.pdf"), undefined, { + type: "application/pdf", + }), + betas: ["files-api-2025-04-14"], +}); + +console.log(`File ID: ${uploaded.id}`); +console.log(`Size: ${uploaded.size_bytes} bytes`); +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```typescript +const response = await client.beta.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { type: "text", text: "Summarize the key findings in this report." }, + { + type: "document", + source: { type: "file", file_id: uploaded.id }, + title: "Q4 Report", + citations: { enabled: true }, + }, + ], + }, + ], + betas: ["files-api-2025-04-14"], +}); + +console.log(response.content[0].text); +``` + +--- + +## Manage Files + +### List Files + +```typescript +const files = await client.beta.files.list({ + betas: ["files-api-2025-04-14"], +}); +for (const f of files.data) { + console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`); +} +``` + +### Delete a File + +```typescript +await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", { + betas: ["files-api-2025-04-14"], +}); +``` + +### Download a File + +```typescript +const response = await client.beta.files.download( + "file_011CNha8iCJcU1wXNR6q4V8w", + { betas: ["files-api-2025-04-14"] }, +); +const content = Buffer.from(await response.arrayBuffer()); +await fs.promises.writeFile("output.txt", content); +``` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/claude-api/streaming.md b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/streaming.md new file mode 100644 index 0000000..f6a450f --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/streaming.md @@ -0,0 +1,178 @@ +# Streaming — TypeScript + +## Quick Start + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a story" }], +}); + +for await (const event of stream) { + if ( + event.type === "content_block_delta" && + event.delta.type === "text_delta" + ) { + process.stdout.write(event.delta.text); + } +} +``` + +--- + +## Handling Different Content Types + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + thinking: { type: "adaptive" }, + messages: [{ role: "user", content: "Analyze this problem" }], +}); + +for await (const event of stream) { + switch (event.type) { + case "content_block_start": + switch (event.content_block.type) { + case "thinking": + console.log("\n[Thinking...]"); + break; + case "text": + console.log("\n[Response:]"); + break; + } + break; + case "content_block_delta": + switch (event.delta.type) { + case "thinking_delta": + process.stdout.write(event.delta.thinking); + break; + case "text_delta": + process.stdout.write(event.delta.text); + break; + } + break; + } +} +``` + +--- + +## Streaming with Tool Use (Tool Runner) + +Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + }), + run: async ({ location }) => `72°F and sunny in ${location}`, +}); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools: [getWeather], + messages: [ + { role: "user", content: "What's the weather in Paris and London?" }, + ], + stream: true, +}); + +// Outer loop: each tool runner iteration +for await (const messageStream of runner) { + // Inner loop: stream events for this iteration + for await (const event of messageStream) { + switch (event.type) { + case "content_block_delta": + switch (event.delta.type) { + case "text_delta": + process.stdout.write(event.delta.text); + break; + case "input_json_delta": + // Tool input being streamed + break; + } + break; + } + } +} +``` + +--- + +## Getting the Final Message + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Hello" }], +}); + +for await (const event of stream) { + // Process events... +} + +const finalMessage = await stream.finalMessage(); +console.log(`Tokens used: ${finalMessage.usage.output_tokens}`); +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `process.stdout.write()` for immediate display +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally +5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates +6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events +7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop + +## Raw SSE Format + +If using raw HTTP (not SDKs), the stream returns Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/claude-api/tool-use.md b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/tool-use.md new file mode 100644 index 0000000..28525c6 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/claude-api/tool-use.md @@ -0,0 +1,527 @@ +# Tool Use — TypeScript + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the TypeScript SDK. + +Use `betaZodTool` with Zod schemas to define tools with a `run` function, then pass them to `client.beta.messages.toolRunner()`: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + unit: z.enum(["celsius", "fahrenheit"]).optional(), + }), + run: async (input) => { + // Your implementation here + return `72°F and sunny in ${input.location}`; + }, +}); + +// The tool runner handles the agentic loop and returns the final message +const finalMessage = await client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [getWeather], + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +console.log(finalMessage.content); +``` + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via Zod schemas +- Tool schemas are generated automatically from Zod definitions +- Iteration stops automatically when Claude has no more tool calls + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval): + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; // Your tool definitions +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: messages, + }); + + if (response.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (response.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: response.content }); + continue; + } + + const toolUseBlocks = response.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: response.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +### Streaming Manual Loop + +Use `client.messages.stream()` + `finalMessage()` instead of `.create()` when you need streaming within a manual loop. Text deltas are streamed on each iteration; `finalMessage()` collects the complete `Message` so you can inspect `stop_reason` and extract tool-use blocks: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools, + messages, + }); + + // Stream text deltas on each iteration + stream.on("text", (delta) => { + process.stdout.write(delta); + }); + + // finalMessage() resolves with the complete Message — no need to + // manually wire up .on("message") / .on("error") / .on("abort") + const message = await stream.finalMessage(); + + if (message.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (message.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: message.content }); + continue; + } + + const toolUseBlocks = message.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: message.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +> **Important:** Don't wrap `.on()` events in `new Promise()` to collect the final message — use `stream.finalMessage()` instead. The SDK handles all error/abort/completion states internally. + +> **Error handling in the loop:** Use the SDK's typed exceptions (e.g., `Anthropic.RateLimitError`, `Anthropic.APIError`) — see [Error Handling](./README.md#error-handling) for examples. Don't check error messages with string matching. + +> **SDK types:** Use `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.ToolUseBlock`, `Anthropic.ToolResultBlockParam`, `Anthropic.Message`, etc. for all API-related data structures. Don't redefine equivalent interfaces. + +--- + +## Handling Tool Results + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +for (const block of response.content) { + if (block.type === "tool_use") { + const result = await executeTool(block.name, block.input); + + const followup = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [ + { role: "user", content: "What's the weather in Paris?" }, + { role: "assistant", content: response.content }, + { + role: "user", + content: [ + { type: "tool_result", tool_use_id: block.id, content: result }, + ], + }, + ], + }); + } +} +``` + +--- + +## Tool Choice + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + tool_choice: { type: "tool", name: "get_weather" }, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); +``` + +--- + +## Server-Side Tools + +Version-suffixed `type` literals; `name` is fixed per interface. Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322. + +**Don't type-annotate as `Tool[]`** — `Tool` is just the custom-tool variant. Let structural typing infer from the `tools` param, or annotate as `Anthropic.Messages.ToolUnion[]` if you must: + +```typescript +// ✓ let inference work — no annotation +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [ + { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, + { type: "bash_20250124", name: "bash" }, + { type: "web_search_20260209", name: "web_search" }, + { type: "code_execution_20260120", name: "code_execution" }, + ], + messages: [{ role: "user", content: "..." }], +}); + +// ✗ this is a TS2352 — Tool is the CUSTOM tool variant only +// const tools: Anthropic.Tool[] = [{ type: "text_editor_20250728", ... }] +``` + +| Interface | `name` | `type` | +|---|---|---| +| `ToolTextEditor20250124` | `str_replace_editor` | `text_editor_20250124` | +| `ToolTextEditor20250429` | `str_replace_based_edit_tool` | `text_editor_20250429` | +| `ToolTextEditor20250728` | `str_replace_based_edit_tool` | `text_editor_20250728` | +| `ToolBash20250124` | `bash` | `bash_20250124` | +| `WebSearchTool20260209` | `web_search` | `web_search_20260209` | +| `WebFetchTool20260209` | `web_fetch` | `web_fetch_20260209` | +| `CodeExecutionTool20260120` | `code_execution` | `code_execution_20260120` | + +**Don't mix beta and non-beta types**: if you call `client.beta.messages.create()`, the response `content` is `BetaContentBlock[]` — you cannot pass that to a non-beta `ContentBlockParam[]` without narrowing each element. + +--- + + +## Code Execution + +### Basic Usage + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +### Reading Local Files (ESM note) + +`__dirname` doesn't exist in ES modules. For script-relative paths use `import.meta.url`: + +```typescript +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pdfBytes = readFileSync(join(__dirname, "sample.pdf")); +``` + +Or use a CWD-relative path if the script runs from a known directory: `readFileSync("./sample.pdf")`. + +### Upload Files for Analysis + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import { createReadStream } from "fs"; + +const client = new Anthropic(); + +// 1. Upload a file +const uploaded = await client.beta.files.upload({ + file: await toFile(createReadStream("sales_data.csv"), undefined, { + type: "text/csv", + }), + betas: ["files-api-2025-04-14"], +}); + +// 2. Pass to code execution +// Code execution is GA; Files API is still beta (pass via RequestOptions) +const response = await client.messages.create( + { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "Analyze this sales data. Show trends and create a visualization.", + }, + { type: "container_upload", file_id: uploaded.id }, + ], + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], + }, + { headers: { "anthropic-beta": "files-api-2025-04-14" } }, +); +``` + +### Retrieve Generated Files + +```typescript +import path from "path"; +import fs from "fs"; + +const OUTPUT_DIR = "./claude_outputs"; +await fs.promises.mkdir(OUTPUT_DIR, { recursive: true }); + +for (const block of response.content) { + if (block.type === "bash_code_execution_tool_result") { + const result = block.content; + if (result.type === "bash_code_execution_result" && result.content) { + for (const fileRef of result.content) { + if (fileRef.type === "bash_code_execution_output") { + const metadata = await client.beta.files.retrieveMetadata( + fileRef.file_id, + ); + const downloadResponse = await client.beta.files.download(fileRef.file_id); + const fileBytes = Buffer.from(await downloadResponse.arrayBuffer()); + const safeName = path.basename(metadata.filename); + if (!safeName || safeName === "." || safeName === "..") { + console.warn(`Skipping invalid filename: ${metadata.filename}`); + continue; + } + const outputPath = path.join(OUTPUT_DIR, safeName); + await fs.promises.writeFile(outputPath, fileBytes); + console.log(`Saved: ${outputPath}`); + } + } + } + } +} +``` + +### Container Reuse + +```typescript +// First request: set up environment +const response1 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Install tabulate and create data.json with sample user data", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); + +// Reuse container +// container is nullable — set only when using server-side code execution +const containerId = response1.container!.id; + +const response2 = await client.messages.create({ + container: containerId, + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Read data.json and display as a formatted table", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +--- + +## Memory Tool + +### Basic Usage + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Remember that my preferred language is TypeScript.", + }, + ], + tools: [{ type: "memory_20250818", name: "memory" }], +}); +``` + +### SDK Memory Helper + +Use `betaMemoryTool` with a `MemoryToolHandlers` implementation: + +```typescript +import { + betaMemoryTool, + type MemoryToolHandlers, +} from "@anthropic-ai/sdk/helpers/beta/memory"; + +const handlers: MemoryToolHandlers = { + async view(command) { ... }, + async create(command) { ... }, + async str_replace(command) { ... }, + async insert(command) { ... }, + async delete(command) { ... }, + async rename(command) { ... }, +}; + +const memory = betaMemoryTool(handlers); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [memory], + messages: [{ role: "user", content: "Remember my preferences" }], +}); + +for await (const message of runner) { + console.log(message); +} +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts` + +--- + +## Structured Outputs + +### JSON Outputs (Zod — Recommended) + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { z } from "zod"; +import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; + +const ContactInfoSchema = z.object({ + name: z.string(), + email: z.string(), + plan: z.string(), + interests: z.array(z.string()), + demo_requested: z.boolean(), +}); + +const client = new Anthropic(); + +const response = await client.messages.parse({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.", + }, + ], + output_config: { + format: zodOutputFormat(ContactInfoSchema), + }, +}); + +// parsed_output is null if parsing failed — assert or guard +console.log(response.parsed_output!.name); // "Jane Doe" +``` + +### Strict Tool Use + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Book a flight to Tokyo for 2 passengers on March 15", + }, + ], + tools: [ + { + name: "book_flight", + description: "Book a flight to a destination", + strict: true, + input_schema: { + type: "object", + properties: { + destination: { type: "string" }, + date: { type: "string", format: "date" }, + passengers: { + type: "integer", + enum: [1, 2, 3, 4, 5, 6, 7, 8], + }, + }, + required: ["destination", "date", "passengers"], + additionalProperties: false, + }, + }, + ], +}); +``` diff --git a/junie/versions/2206.3/skills/claude-api/typescript/managed-agents/README.md b/junie/versions/2206.3/skills/claude-api/typescript/managed-agents/README.md new file mode 100644 index 0000000..b4f2a54 --- /dev/null +++ b/junie/versions/2206.3/skills/claude-api/typescript/managed-agents/README.md @@ -0,0 +1,359 @@ +# Managed Agents — TypeScript + +> **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Create an Environment + +```typescript +const environment = await client.beta.environments.create( + { + name: "my-dev-env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, + }, +); +console.log(environment.id); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent: { type: "agent", id: agent.id }`. + +### Minimal + +```typescript +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }], + }, +); + +// 2. Start a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + }, +); +console.log(session.id, session.status); +``` + +### With system prompt and custom tools + +```typescript +const agent = await client.beta.agents.create( + { + name: "Code Reviewer", + model: "claude-opus-4-6", + system: "You are a senior code reviewer.", + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { + type: "custom", + name: "run_tests", + description: "Run the test suite", + input_schema: { + type: "object", + properties: { + test_path: { type: "string", description: "Path to test file" }, + }, + required: ["test_path"], + }, + }, + ], + }, +); + +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + title: "Code review session", + resources: [ + { + type: "github_repository", + url: "https://github.com/owner/repo", + mount_path: "/workspace/repo", + authorization_token: process.env.GITHUB_TOKEN, + branch: "main", + }, + ], + }, +); +``` + +--- + +## Send a User Message + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.message", + content: [{ type: "text", text: "Review the auth module" }], + }, + ], + }, +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```typescript +// Stream-first: open stream and send concurrently +const [events] = await Promise.all([ + collectStream(session.id), + client.beta.sessions.events.send( + session.id, + { events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] }, + ), +]); + +// Standalone stream iteration: +const stream = await client.beta.sessions.stream( + session.id, +); + +for await (const event of stream) { + switch (event.type) { + case "agent.message": + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + break; + case "agent.custom_tool_use": + // Custom tool invocation — session is now idle + console.log(`\nCustom tool call: ${event.tool_name}`); + console.log(`Input: ${JSON.stringify(event.input)}`); + break; + case "session.status_idle": + console.log("\n--- Agent idle ---"); + break; + case "session.status_terminated": + console.log("\n--- Session terminated ---"); + break; + } +} +``` + +--- + +## Provide Custom Tool Result + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.custom_tool_result", + custom_tool_use_id: "sevt_abc123", + content: [{ type: "text", text: "All 42 tests passed." }], + }, + ], + }, +); +``` + +--- + +## Poll Events + +```typescript +const events = await client.beta.sessions.events.list( + session.id, +); +for (const event of events.data) { + console.log(`${event.type}: ${event.id}`); +} +``` + +--- + +## Full Streaming Loop with Custom Tools + +```typescript +function runCustomTool(toolName: string, toolInput: unknown): string { + if (toolName === "run_tests") { + // Your tool implementation here + return "All tests passed."; + } + return `Unknown tool: ${toolName}`; +} + +async function runSession(client: Anthropic, sessionId: string) { + while (true) { + const stream = await client.beta.sessions.stream( + sessionId, + ); + + const toolCalls: Array<{ custom_tool_use_id: string; tool_name: string; input: unknown }> = []; + + for await (const event of stream) { + if (event.type === "agent.message") { + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + } else if (event.type === "agent.custom_tool_use") { + toolCalls.push({ + id: event.id, + tool_name: event.tool_name, + input: event.input, + }); + } else if (event.type === "session.status_idle") { + break; + } else if (event.type === "session.status_terminated") { + return; + } + } + + if (toolCalls.length === 0) break; + + // Process custom tool calls + const results = toolCalls.map((call) => ({ + type: "user.custom_tool_result" as const, + custom_tool_use_id: call.id, + content: [{ type: "text" as const, text: runCustomTool(call.tool_name, call.input) }], + })); + + await client.beta.sessions.events.send( + sessionId, + { events: results }, + ); + } +} +``` + +--- + +## Upload a File + +```typescript +import fs from "fs"; + +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// Use in a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }], + }, +); +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```typescript +import fs from "fs"; + +// List files associated with a session +const files = await client.beta.files.list({ + scope: session.id, +}); +for (const f of files.data) { + console.log(f.filename, f.size_bytes); + + // Download and save to disk + const resp = await client.beta.files.download(f.id); + const buffer = Buffer.from(await resp.arrayBuffer()); + fs.writeFileSync(f.filename, buffer); +} +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty. + +--- + +## Session Management + +```typescript +// Get session details +const session = await client.beta.sessions.retrieve("sess_abc123"); +console.log(session.status, session.usage); + +// List sessions +const sessions = await client.beta.sessions.list(); + +// Delete a session +await client.beta.sessions.delete("sess_abc123"); + +// Archive a session +await client.beta.sessions.archive("sess_abc123"); +``` + +--- + +## MCP Server Integration + +```typescript +// Agent declares MCP server (no auth here — auth goes in a vault) +const agent = await client.beta.agents.create({ + name: "MCP Agent", + model: "claude-opus-4-6", + mcp_servers: [ + { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" }, + ], + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { type: "mcp_toolset", mcp_server_name: "my-tools" }, + ], +}); + +// Session attaches vault(s) containing credentials for those MCP server URLs +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], +}); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2206.3/skills/demo-setup/SKILL.md b/junie/versions/2206.3/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2206.3/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2206.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2206.3/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2206.3/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/BYOK.md b/junie/versions/2206.3/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..7008ef3 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,186 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..fda784a --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,144 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2206.3/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2206.3/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..8cf3e64 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..234cc05 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,75 @@ +# Worktrees + + + + + Slash command to open the worktree menu: /worktree + + +Junie CLI integrates with [Git worktrees](https://git-scm.com/docs/git-worktree) to help you work on multiple +tasks in the same repository without branch conflicts. You can use existing worktrees, create new ones with +predefined names, and switch between them — all without leaving Junie. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own +working tree and index, so you can have different branches checked out simultaneously. Junie CLI makes it easy to +manage worktrees and switch the agent between them. + +## The /worktree command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name + (`-junie-wt-01`, `-02`, and so on) as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, the agent completely resets its state to the new worktree. This makes `/worktree` ideal for +use before starting a new task. + +### Typical workflow + +1. Pre-create a few worktrees so that build caches are ready in each one. +2. When you start a new task, run `/worktree` and switch to one of the prepared worktrees. +3. Prompt Junie to create a branch and rebase to fresh `main`. +4. Work on the task in the worktree while the original directory stays untouched. + +### Transferring uncommitted changes + +If your current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to +transfer them or start clean: + +- **Transfer changes**: Junie uses `git stash` to move uncommitted changes from the source directory to the + target worktree. +- **Start clean**: the worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly (for example, due to conflicts), Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + +## Concurrent session detection + +When a second Junie instance starts on the same project directory, Junie detects the conflict and reminds you +about possible issues with two agents operating on the same files. It then offers to switch to a worktree so +each instance works in its own isolated directory. + +This serves two purposes: + +- **Workspace management**: prevents two agents from making conflicting changes to the same files. +- **Onboarding**: helps you discover worktree support in Junie CLI if you haven't used it before. + +## Auto worktree detection + +If the agent navigates to a worktree directory during a session — whether because you prompted it to or a shell +command changed the working directory — Junie detects the switch and offers to restart with a clean task in the +new worktree. + +Accepting the restart: + +- Prevents the agent from continuing to operate on files in the old worktree. +- Switches the Junie project to the new directory, which affects where Junie looks for the `.junie` folder, + loads skills, reads MCP configurations, and so on. + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory (for example, + `../my-project-junie-wt-01`). Make sure the parent directory is writable. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..df04555 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,138 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..2db6e77 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,450 @@ +# Demo agent + + + +Slash command to invoke the demo agent: /demo + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..1498840 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..4a1ba6f --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,334 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts a new session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Clear up session context + +Use `/new` to clear up the context of the current session and start a new session in Junie CLI interactive mode. +Use `/new ` to start a new session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Resume previous sessions + +To see the session history and resume one of the previous sessions, use `/history`. + +Junie CLI stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2206.3/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2206.3/skills/junie-cli-docs/SKILL.md b/junie/versions/2206.3/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..3f27929 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4001 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts a new session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Clear up session context + +Use `/new` to clear up the context of the current session and start a new session in Junie CLI interactive mode. +Use `/new ` to start a new session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Resume previous sessions + +To see the session history and resume one of the previous sessions, use `/history`. + +Junie CLI stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens a new session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | See the session history and resume one of the previous sessions. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Clear up the context and start a new session. If you provide ``, Junie opens the new session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated git worktree for parallel work. See [Worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Worktrees + +# Worktrees + + + + + Slash command to open the worktree menu: /worktree + + +Junie CLI integrates with [Git worktrees](https://git-scm.com/docs/git-worktree) to help you work on multiple +tasks in the same repository without branch conflicts. You can use existing worktrees, create new ones with +predefined names, and switch between them — all without leaving Junie. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own +working tree and index, so you can have different branches checked out simultaneously. Junie CLI makes it easy to +manage worktrees and switch the agent between them. + +## The /worktree command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name + (`-junie-wt-01`, `-02`, and so on) as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, the agent completely resets its state to the new worktree. This makes `/worktree` ideal for +use before starting a new task. + +### Typical workflow + +1. Pre-create a few worktrees so that build caches are ready in each one. +2. When you start a new task, run `/worktree` and switch to one of the prepared worktrees. +3. Prompt Junie to create a branch and rebase to fresh `main`. +4. Work on the task in the worktree while the original directory stays untouched. + +### Transferring uncommitted changes + +If your current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to +transfer them or start clean: + +- **Transfer changes**: Junie uses `git stash` to move uncommitted changes from the source directory to the + target worktree. +- **Start clean**: the worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly (for example, due to conflicts), Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + +## Concurrent session detection + +When a second Junie instance starts on the same project directory, Junie detects the conflict and reminds you +about possible issues with two agents operating on the same files. It then offers to switch to a worktree so +each instance works in its own isolated directory. + +This serves two purposes: + +- **Workspace management**: prevents two agents from making conflicting changes to the same files. +- **Onboarding**: helps you discover worktree support in Junie CLI if you haven't used it before. + +## Auto worktree detection + +If the agent navigates to a worktree directory during a session — whether because you prompted it to or a shell +command changed the working directory — Junie detects the switch and offers to restart with a clean task in the +new worktree. + +Accepting the restart: + +- Prevents the agent from continuing to operate on files in the old worktree. +- Switches the Junie project to the new directory, which affects where Junie looks for the `.junie` folder, + loads skills, reads MCP configurations, and so on. + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory (for example, + `../my-project-junie-wt-01`). Make sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + +Slash command to invoke the demo agent: /demo + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2206.3/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2206.3/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..77483e4 --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens a new session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | See the session history and resume one of the previous sessions. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Clear up the context and start a new session. If you provide ``, Junie opens the new session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated git worktree for parallel work. See [Worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + + diff --git a/junie/versions/2206.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2206.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..7a888ac --- /dev/null +++ b/junie/versions/2206.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,157 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2206.4/skills/claude-api/LICENSE.txt b/junie/versions/2206.4/skills/claude-api/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/junie/versions/2206.4/skills/claude-api/SKILL.md b/junie/versions/2206.4/skills/claude-api/SKILL.md new file mode 100644 index 0000000..1431d44 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/SKILL.md @@ -0,0 +1,317 @@ +--- +name: claude-api +description: "Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. TRIGGER when: code imports anthropic/@anthropic-ai/sdk; user asks to use the Claude API, Anthropic SDKs, or Managed Agents (/v1/agents, /v1/sessions, /v1/environments). DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks." +license: Complete terms in LICENSE.txt +--- + + +# Building LLM-Powered Applications with Claude + +This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation. + +## Before You Start + +Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — `import openai`, `from openai`, `langchain_openai`, `OpenAI(`, `gpt-4`, `gpt-5`, file names like `agent-openai.py` or `*-generic.py`, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls. + +## Output Requirement + +When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of: + +1. **The official Anthropic SDK** for the project's language (`anthropic`, `@anthropic-ai/sdk`, `com.anthropic.*`, etc.). This is the default whenever a supported SDK exists for the project. +2. **Raw HTTP** (`curl`, `requests`, `fetch`, `httpx`, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK. + +Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims. + +**Never guess SDK usage.** Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the `{lang}/` files in this skill or the official SDK repositories or documentation links listed in `shared/live-sources.md`. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from `shared/live-sources.md` before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK. + +## Defaults + +Unless the user requests otherwise: + +For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string `claude-opus-4-6`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events + +--- + +## Subcommands + +If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every **Subcommands** table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via `/claude-api `. If no table in the document matches, treat the request as normal prose. + + + +--- + +## Language Detection + +Before reading code examples, determine which language the user is working in: + +1. **Look at project files** to infer the language: + + - `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/` + - `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/` + - `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/` + - `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/` + - `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/` + - `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/` + - `*.go`, `go.mod` → **Go** — read from `go/` + - `*.rb`, `Gemfile` → **Ruby** — read from `ruby/` + - `*.cs`, `*.csproj` → **C#** — read from `csharp/` + - `*.php`, `composer.json` → **PHP** — read from `php/` + +2. **If multiple languages detected** (e.g., both Python and TypeScript files): + + - Check which language the user's current file or question relates to + - If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?" + +3. **If language can't be inferred** (empty project, no source files, or unsupported language): + + - Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP + - If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language." + +4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.): + + - Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist + - Offer to show Python or TypeScript examples as reference implementations + +5. **If user needs cURL/raw HTTP examples**, read from `curl/`. + +### Language-Specific Feature Support + +| Language | Tool Runner | Managed Agents | Notes | +| ---------- | ----------- | -------------- | ------------------------------------- | +| Python | Yes (beta) | Yes (beta) | Full support — `@beta_tool` decorator | +| TypeScript | Yes (beta) | Yes (beta) | Full support — `betaZodTool` + Zod | +| Java | Yes (beta) | Yes (beta) | Beta tool use with annotated classes | +| Go | Yes (beta) | Yes (beta) | `BetaToolRunner` in `toolrunner` pkg | +| Ruby | Yes (beta) | Yes (beta) | `BaseTool` + `tool_runner` in beta | +| C# | No | No | Official SDK | +| PHP | Yes (beta) | Yes (beta) | `BetaRunnableTool` + `toolRunner()` | +| cURL | N/A | Yes (beta) | Raw HTTP, no SDK features | + +> **Managed Agents code examples**: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`). Read your language's README plus the language-agnostic `shared/managed-agents-*.md` concept files. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. If a binding you need isn't shown in the README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use cURL-style raw HTTP requests against the API. + +--- + +## Which Surface Should I Use? + +> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration. + +| Use Case | Tier | Recommended Surface | Why | +| ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ | +| Classification, summarization, extraction, Q&A | Single LLM call | **Claude API** | One request, one response | +| Batch processing or embeddings | Single LLM call | **Claude API** | Specialized endpoints | +| Multi-step pipelines with code-controlled logic | Workflow | **Claude API + tool use** | You orchestrate the loop | +| Custom agent with your own tools | Agent | **Claude API + tool use** | Maximum flexibility | +| Server-managed stateful agent with workspace | Agent | **Managed Agents** | Anthropic runs the loop and hosts the tool-execution sandbox | +| Persisted, versioned agent configs | Agent | **Managed Agents** | Agents are stored objects; sessions pin to a version | +| Long-running multi-turn agent with file mounts | Agent | **Managed Agents** | Per-session containers, SSE event stream, Skills + MCP | + +> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution). + +> **Third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry):** Managed Agents is **not available** on Bedrock, Vertex, or Foundry. If you are deploying through any third-party provider, use **Claude API + tool use** for all use cases — including ones where Managed Agents would otherwise be the recommended surface. + +### Decision Tree + +``` +What does your application need? + +0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry? + └── Yes → Claude API (+ tool use for agents) — Managed Agents is 1P only. + No → continue. + +1. Single LLM call (classification, summarization, extraction, Q&A) + └── Claude API — one request, one response + +2. Do you want Anthropic to run the agent loop and host a per-session + container where Claude executes tools (bash, file ops, code)? + └── Yes → Managed Agents — server-managed sessions, persisted agent configs, + SSE event stream, Skills + MCP, file mounts. + Examples: "stateful coding agent with a workspace per task", + "long-running research agent that streams events to a UI", + "agent with persisted, versioned config used across many sessions" + +3. Workflow (multi-step, code-orchestrated, with your own tools) + └── Claude API with tool use — you control the loop + +4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute) + └── Claude API agentic loop (maximum flexibility) +``` + +### Should I Build an Agent? + +Before choosing the agent tier, check all four criteria: + +- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF") +- **Value** — Does the outcome justify higher cost and latency? +- **Viability** — Is Claude capable at this task type? +- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback) + +If the answer is "no" to any of these, stay at a simpler tier (single call or workflow). + +--- + +## Architecture + +Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs. + +**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually. + +**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted. + +**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`. + +**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests. + +--- + +## Current Models (cached: 2026-02-17) + +| Model | Model ID | Context | Input $/1M | Output $/1M | +| ----------------- | ------------------- | -------------- | ---------- | ----------- | +| Claude Opus 4.6 | `claude-opus-4-6` | 200K (1M beta) | $5.00 | $25.00 | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00 | $15.00 | +| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 | + +**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. + +**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself. + +A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that. + +**Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples. + +--- + +## Thinking & Effort (Quick Reference) + +**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` and do NOT switch to an older model.** + +**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — `medium` is often a favorable balance; use `max` when correctness matters more than cost; use `low` for subagents or simple tasks. + +**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead. + +**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.6 with adaptive thinking instead. + +--- + +## Compaction (Quick Reference) + +**Beta, Opus 4.6 and Sonnet 4.6.** For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`. + +**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state. + +See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`. + +--- + +## Prompt Caching (Quick Reference) + +**Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint. + +**Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache. + +**Verify with `usage.cache_read_input_tokens`** — if it's zero across repeated requests, a silent invalidator is at work (`datetime.now()` in system prompt, unsorted JSON, varying tool set). + +For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read `shared/prompt-caching.md`. Language-specific syntax: `{lang}/claude-api/README.md` (Prompt Caching section). + +--- + +## Managed Agents (Beta) + +**Managed Agents** is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (`POST /v1/agents`), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back. + +**Managed Agents is first-party only.** It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. For agents on third-party providers, use Claude API + tool use. + +**Mandatory flow:** Agent (once) → Session (every run). `model`/`system`/`tools` live on the agent, never the session. See `shared/managed-agents-overview.md` for the full reading guide, beta headers, and pitfalls. + +**Beta headers:** `managed-agents-2026-04-01` — the SDK sets this automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills API uses `skills-2025-10-02` and Files API uses `files-api-2025-04-14`, but you don't need to explicitly pass those in for endpoints other than `/v1/skills` and `/v1/files`. + +**Subcommands** — invoke directly with `/claude-api `: + +| Subcommand | Action | +|---|---| +| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: mental model → know-or-explore branch → template config → session setup → emit code. Do not summarize — run the interview. | + +**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use raw HTTP from `curl/managed-agents.md` as a reference. + +**When the user wants to set up a Managed Agent from scratch** (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read `shared/managed-agents-onboarding.md` and run its interview — same flow as the `managed-agents-onboard` subcommand. + +**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc. + +--- + +## Reading Guide + +After detecting the language, read the relevant files based on what the user needs: + +### Quick Task Reference + +**Single text classification/summarization/extraction/Q&A:** +→ Read only `{lang}/claude-api/README.md` + +**Chat UI or real-time response display:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md` + +**Long-running conversations (may exceed context window):** +→ Read `{lang}/claude-api/README.md` — see Compaction section + +**Prompt caching / optimize caching / "why is my cache hit rate low":** +→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section) + +**Function calling / tool use / agents:** +→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` + +**Agent design (tool surface, context management, caching strategy):** +→ Read `shared/agent-design.md` + +**Batch processing (non-latency-sensitive):** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md` + +**File uploads across multiple requests:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md` + +**Managed Agents (server-managed stateful agents with workspace):** +→ Read `shared/managed-agents-overview.md` + the rest of the `shared/managed-agents-*.md` files. For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently support Managed Agents — use raw HTTP from `curl/managed-agents.md` as a reference. + +### Claude API (Full File Reference) + +Read the **language-specific Claude API folder** (`{language}/claude-api/`): + +1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling. +2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations. +3. **`shared/agent-design.md`** — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles. +4. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs). +5. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally. +6. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost. +7. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading. +8. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache. +9. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling. +10. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation. + +> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed. + +> **Note:** For the Managed Agents file reference, see the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs. + +--- + +## When to Use WebFetch + +Use WebFetch to get the latest documentation when: + +- User asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered here + +Live documentation URLs are in `shared/live-sources.md`. + +## Common Pitfalls + +- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating. +- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong. +- **Opus 4.6 prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. +- **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, or deliberately short outputs. +- **128K output tokens:** Opus 4.6 supports up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`. +- **Tool call JSON parsing (Opus 4.6):** Opus 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input. +- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific. +- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces. +- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety. +- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text. diff --git a/junie/versions/2206.4/skills/claude-api/csharp/claude-api.md b/junie/versions/2206.4/skills/claude-api/csharp/claude-api.md new file mode 100644 index 0000000..e0e790a --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/csharp/claude-api.md @@ -0,0 +1,402 @@ +# Claude API — C# + +> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation. + +## Installation + +```bash +dotnet add package Anthropic +``` + +## Client Initialization + +```csharp +using Anthropic; + +// Default (uses ANTHROPIC_API_KEY env var) +AnthropicClient client = new(); + +// Explicit API key (use environment variables — never hardcode keys) +AnthropicClient client = new() { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") +}; +``` + +--- + +## Basic Message Request + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }] +}; +var response = await client.Messages.Create(parameters); + +// ContentBlock is a union wrapper. .Value unwraps to the variant object, +// then OfType filters to the type you want. Or use the TryPick* idiom +// shown in the Thinking section below. +foreach (var text in response.Content.Select(b => b.Value).OfType()) +{ + Console.WriteLine(text.Text); +} +``` + +--- + +## Streaming + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 64000, + Messages = [new() { Role = Role.User, Content = "Write a haiku" }] +}; + +await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters)) +{ + if (streamEvent.TryPickContentBlockDelta(out var delta) && + delta.Delta.TryPickText(out var text)) + { + Console.Write(text.Text); + } +} +``` + +**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`. + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```csharp +using Anthropic.Models.Messages; + +var response = await client.Messages.Create(new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + // ThinkingConfigParam? implicitly converts from the concrete variant classes — + // no wrapper needed. + Thinking = new ThinkingConfigAdaptive(), + Messages = + [ + new() { Role = Role.User, Content = "Solve: 27 * 453" }, + ], +}); + +// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union. +foreach (var block in response.Content) +{ + if (block.TryPickThinking(out ThinkingBlock? t)) + { + Console.WriteLine($"[thinking] {t.Thinking}"); + } + else if (block.TryPickText(out TextBlock? text)) + { + Console.WriteLine(text.Text); + } +} +``` + +> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +Alternative to `TryPick*`: `.Select(b => b.Value).OfType()` (same LINQ pattern as the Basic Message example). + +--- + +## Tool Use + +### Defining a tool + +`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`. + +```csharp +using System.Text.Json; +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeSonnet4_6, + MaxTokens = 16000, + Tools = [ + new Tool { + Name = "get_weather", + Description = "Get the current weather in a given location", + InputSchema = new() { + Properties = new Dictionary { + ["location"] = JsonSerializer.SerializeToElement( + new { type = "string", description = "City name" }), + }, + Required = ["location"], + }, + }, + ], + Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }], +}; +``` + +Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion). + +See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. +### Converting response content to the follow-up assistant message + +When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path). + +```csharp +using Anthropic.Models.Messages; + +Message response = await client.Messages.Create(parameters); + +// No .ToParam() — reconstruct per variant. Implicit conversions from each +// *Param type to ContentBlockParam mean no explicit wrapper. +List assistantContent = []; +List toolResults = []; +foreach (ContentBlock block in response.Content) +{ + if (block.TryPickText(out TextBlock? text)) + { + assistantContent.Add(new TextBlockParam { Text = text.Text }); + } + else if (block.TryPickThinking(out ThinkingBlock? thinking)) + { + // Signature MUST be preserved — the API rejects tampering + assistantContent.Add(new ThinkingBlockParam + { + Thinking = thinking.Thinking, + Signature = thinking.Signature, + }); + } + else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted)) + { + assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data }); + } + else if (block.TryPickToolUse(out ToolUseBlock? toolUse)) + { + // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it + assistantContent.Add(new ToolUseBlockParam + { + ID = toolUse.ID, + Name = toolUse.Name, + Input = toolUse.Input, + }); + // Execute the tool; collect ONE result per tool_use block — the API + // rejects the follow-up if any tool_use ID lacks a matching tool_result. + string result = ExecuteYourTool(toolUse.Name, toolUse.Input); + toolResults.Add(new ToolResultBlockParam + { + ToolUseID = toolUse.ID, + Content = result, + }); + } +} + +// Follow-up: prior messages + assistant echo + user tool_result(s) +List followUpMessages = +[ + .. parameters.Messages, + new() { Role = Role.Assistant, Content = assistantContent }, + new() { Role = Role.User, Content = toolResults }, +]; +``` + +`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts. + +--- + +## Context Editing / Compaction (Beta) + +**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`: + +```csharp +using Anthropic.Models.Beta.Messages; +using NonBeta = Anthropic.Models.Messages; // only if you also need non-beta types +// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed) +``` + + +`BetaMessage.Content` is `IReadOnlyList` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block: + +```csharp +using Anthropic.Models.Beta.Messages; + +var betaParams = new MessageCreateParams // no Beta prefix — one of only 2 unprefixed +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Betas = ["compact-2026-01-12"], + ContextManagement = new BetaContextManagementConfig + { + Edits = [new BetaCompact20260112Edit()], + }, + Messages = messages, +}; +BetaMessage resp = await client.Beta.Messages.Create(betaParams); + +foreach (BetaContentBlock block in resp.Content) +{ + if (block.TryPickCompaction(out BetaCompactionBlock? compaction)) + { + // Content is nullable — compaction can fail server-side + Console.WriteLine($"compaction summary: {compaction.Content}"); + } +} + +// Context-edit metadata lives on a separate nullable field +if (resp.ContextManagement is { } ctx) +{ + foreach (var edit in ctx.AppliedEdits) + Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens"); +} + +// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list +// union). It implicit-converts from List, NOT from the +// response's IReadOnlyList. Convert each block: +List paramBlocks = []; +foreach (var b in resp.Content) +{ + if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text }); + else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content }); + // ... other variants as needed +} +messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks }); +``` + +All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`. + +**`BetaToolUseBlock.Input` is `IReadOnlyDictionary`** — index by key then call the `JsonElement` extractor: + +```csharp +if (block.TryPickToolUse(out BetaToolUseBlock? tu)) +{ + int a = tu.Input["a"].GetInt32(); + string s = tu.Input["name"].GetString()!; +} +``` + +--- + +## Effort Parameter + +Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum` has an implicit conversion from the enum, so assign `Effort.High` directly. + +```csharp +OutputConfig = new OutputConfig { Effort = Effort.High }, +``` + +Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control. + +--- + +## Prompt Caching + +`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```csharp +System = new List { + new() { + Text = longSystemPrompt, + CacheControl = new CacheControlEphemeral(), // auto-sets Type = "ephemeral" + }, +}, +``` + +Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`. + +Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`. + +--- + +## Token Counting + +```csharp +MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams { + Model = Model.ClaudeOpus4_6, + Messages = [new() { Role = Role.User, Content = "Hello" }], +}); +long tokens = result.InputTokens; +``` + +`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters. + +--- + +## Structured Output + +```csharp +OutputConfig = new OutputConfig { + Format = new JsonOutputFormat { + Schema = new Dictionary { + ["type"] = JsonSerializer.SerializeToElement("object"), + ["properties"] = JsonSerializer.SerializeToElement( + new { name = new { type = "string" } }), + ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }), + }, + }, +}, +``` + +`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`. + +```csharp +new MessageParam { + Role = Role.User, + Content = new List { + new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } }, + new TextBlockParam { Text = "Summarize this PDF" }, + }, +} +``` + +--- + +## Server-Side Tools + +Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`. + +```csharp +Tools = [ + new WebSearchTool20260209(), + new ToolBash20250124(), + new ToolTextEditor20250728(), + new CodeExecutionTool20260120(), +], +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`. + +--- + +## Files API (Beta) + +Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`. + +```csharp +using Anthropic.Models.Beta.Files; +using Anthropic.Models.Beta.Messages; + +FileMetadata meta = await client.Beta.Files.Upload( + new FileUploadParams { File = File.OpenRead("doc.pdf") }); + +// Referencing the uploaded file requires Beta message types: +new BetaRequestDocumentBlock { + Source = new BetaFileDocumentSource { FileID = meta.ID }, +} +``` + +The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`. diff --git a/junie/versions/2206.4/skills/claude-api/curl/examples.md b/junie/versions/2206.4/skills/claude-api/curl/examples.md new file mode 100644 index 0000000..e08b443 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/curl/examples.md @@ -0,0 +1,216 @@ +# Claude API — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +--- + +## Basic Message Request + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "messages": [ + {"role": "user", "content": "What is the capital of France?"} + ] + }' +``` + +### Parsing the response + +Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` — +JSON strings can contain any character and regex parsing will break on quotes, +escapes, or multi-line content. + +```bash +# Capture the response, then extract fields +response=$(curl -s https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{"model":"claude-opus-4-6","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') + +# Print the first text block (-r strips the JSON quotes) +echo "$response" | jq -r '.content[0].text' + +# Read usage fields +input_tokens=$(echo "$response" | jq -r '.usage.input_tokens') +output_tokens=$(echo "$response" | jq -r '.usage.output_tokens') + +# Read stop reason (for tool-use loops) +stop_reason=$(echo "$response" | jq -r '.stop_reason') + +# Extract all text blocks (content is an array; filter to type=="text") +echo "$response" | jq -r '.content[] | select(.type == "text") | .text' +``` + + +--- + +## Streaming (SSE) + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 64000, + "stream": true, + "messages": [{"role": "user", "content": "Write a haiku"}] + }' +``` + +The response is a stream of Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` + +--- + +## Tool Use + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [{"role": "user", "content": "What is the weather in Paris?"}] + }' +``` + +When Claude responds with a `tool_use` block, send the result back: + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": [ + {"type": "text", "text": "Let me check the weather."}, + {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}} + ]}, + {"role": "user", "content": [ + {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"} + ]} + ] + }' +``` + +--- + +## Prompt Caching + +Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist. + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} + ], + "messages": [{"role": "user", "content": "Summarize the key points"}] + }' +``` + +For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). + +```bash +# Opus 4.6: adaptive thinking (recommended) +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "thinking": { + "type": "adaptive" + }, + "output_config": { + "effort": "high" + }, + "messages": [{"role": "user", "content": "Solve this step by step..."}] + }' +``` + +--- + +## Required Headers + +| Header | Value | Description | +| ------------------- | ------------------ | -------------------------- | +| `Content-Type` | `application/json` | Required | +| `x-api-key` | Your API key | Authentication | +| `anthropic-version` | `2023-06-01` | API version | +| `anthropic-beta` | Beta feature IDs | Required for beta features | diff --git a/junie/versions/2206.4/skills/claude-api/curl/managed-agents.md b/junie/versions/2206.4/skills/claude-api/curl/managed-agents.md new file mode 100644 index 0000000..3a684cf --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/curl/managed-agents.md @@ -0,0 +1,333 @@ +# Managed Agents — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working without an SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" + +# Common headers +HEADERS=( + -H "Content-Type: application/json" + -H "x-api-key: $ANTHROPIC_API_KEY" + -H "anthropic-version: 2023-06-01" + -H "anthropic-beta: managed-agents-2026-04-01" +) +``` + +--- + +## Create an Environment + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "my-dev-env", + "config": { + "type": "cloud", + "networking": { "type": "unrestricted" } + } + }' +``` + +### With restricted networking + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "restricted-env", + "config": { + "type": "cloud", + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } + } + }' +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Under `managed-agents-2026-04-01`, `model`/`system`/`tools` are top-level fields on `POST /v1/agents`, not on the session. Always create the agent first — the session only takes `"agent": {"type": "agent", "id": "..."}`. + +### Minimal + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Coding Assistant", + "model": "claude-opus-4-6", + "tools": [{ "type": "agent_toolset_20260401" }] + }' +# → { "id": "agent_abc123", ... } + +# 2. Start a session +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123" + }' +``` + +### With system prompt, custom tools, and GitHub repo + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Code Reviewer", + "model": "claude-opus-4-6", + "system": "You are a senior code reviewer. Be thorough and constructive.", + "tools": [ + { "type": "agent_toolset_20260401" }, + { + "type": "custom", + "name": "run_linter", + "description": "Run the project linter on a file", + "input_schema": { + "type": "object", + "properties": { + "file_path": { "type": "string", "description": "Path to lint" } + }, + "required": ["file_path"] + } + } + ] + }' + +# 2. Start a session with the repo mounted +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123", + "title": "Code review session", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": "ghp_...", + "branch": "feature-branch" + } + ] + }' +``` + +--- + +## Send a User Message + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.message", + "content": [{ "type": "text", "text": "Review the auth module for security issues" }] + } + ] + }' +``` + +--- + +## Stream Events (SSE) + +```bash +curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + "${HEADERS[@]}" +``` + +Response format: + +``` +event: session.status_running +data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."} + +event: agent.message +data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."} + +event: session.status_idle +data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."} +``` + +--- + +## Poll Events + +```bash +# Get all events +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" + +# Paginated — get next page of events +curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \ + "${HEADERS[@]}" +``` + +--- + +## Provide Custom Tool Result + +When the agent calls a custom tool, send the result back: + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "No linting errors found." }] + } + ] + }' +``` + +--- + +## Interrupt a Running Session + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "interrupt" + } + ] + }' +``` + +--- + +## Get Session Details + +```bash +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## List Sessions + +```bash +curl https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" +``` + +--- + +## Delete a Session + +```bash +curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## Upload a File + +```bash +curl -X POST https://api.anthropic.com/v1/files \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: files-api-2025-04-14" \ + -F "file=@path/to/file.txt" \ + -F "purpose=agent" +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```bash +# List files associated with a session +curl "https://api.anthropic.com/v1/files?scope=$SESSION_ID" \ + "${HEADERS[@]}" + +# Download a specific file +curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ + "${HEADERS[@]}" \ + -o downloaded_file.txt +``` + +--- + +## List Agents + +```bash +curl https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" +``` + +--- + +## MCP Server Integration + +```bash +# 1. Agent declares MCP server (no auth here — auth goes in a vault) +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "MCP Agent", + "model": "claude-opus-4-6", + "mcp_servers": [ + { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" } + ], + "tools": [ + { "type": "agent_toolset_20260401" }, + { "type": "mcp_toolset", "mcp_server_name": "my-tools" } + ] + }' + +# 2. Session attaches vault containing credentials for that MCP server URL +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] + }' +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Tool Configuration + +```bash +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Restricted Agent", + "model": "claude-opus-4-6", + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] + }' +``` diff --git a/junie/versions/2206.4/skills/claude-api/go/claude-api.md b/junie/versions/2206.4/skills/claude-api/go/claude-api.md new file mode 100644 index 0000000..019b80f --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/go/claude-api.md @@ -0,0 +1,421 @@ +# Claude API — Go + +> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) +``` + +--- + +## Basic Message Request + +```go +response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + }, +}) +if err != nil { + log.Fatal(err) +} +for _, block := range response.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + } +} +``` + +--- + +## Streaming + +```go +stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 64000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")), + }, +}) + +for stream.Next() { + event := stream.Current() + switch eventVariant := event.AsAny().(type) { + case anthropic.ContentBlockDeltaEvent: + switch deltaVariant := eventVariant.Delta.AsAny().(type) { + case anthropic.TextDelta: + fmt.Print(deltaVariant.Text) + } + } +} +if err := stream.Err(); err != nil { + log.Fatal(err) +} +``` + +**Accumulating the final message** (there is no `GetFinalMessage()` on the stream): + +```go +stream := client.Messages.NewStreaming(ctx, params) +message := anthropic.Message{} +for stream.Next() { + message.Accumulate(stream.Current()) +} +if err := stream.Err(); err != nil { log.Fatal(err) } +// message.Content now has the complete response +``` + + +--- + +## Tool Use + +### Tool Runner (Beta — Recommended) + +**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package. + +```go +import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/toolrunner" +) + +// Define tool input with jsonschema tags for automatic schema generation +type GetWeatherInput struct { + City string `json:"city" jsonschema:"required,description=The city name"` +} + +// Create a tool with automatic schema generation from struct tags +weatherTool, err := toolrunner.NewBetaToolFromJSONSchema( + "get_weather", + "Get current weather for a city", + func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) { + return anthropic.BetaToolResultBlockParamContentUnion{ + OfText: &anthropic.BetaTextBlockParam{ + Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City), + }, + }, nil + }, +) +if err != nil { + log.Fatal(err) +} + +// Create a tool runner that handles the conversation loop automatically +runner := client.Beta.Messages.NewToolRunner( + []anthropic.BetaTool{weatherTool}, + anthropic.BetaToolRunnerParams{ + BetaMessageNewParams: anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.BetaMessageParam{ + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")), + }, + }, + MaxIterations: 5, + }, +) + +// Run until Claude produces a final response +message, err := runner.RunToCompletion(context.Background()) +if err != nil { + log.Fatal(err) +} + +// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion. +// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock, +// not TextBlock): +for _, block := range message.Content { + switch block := block.AsAny().(type) { + case anthropic.BetaTextBlock: + fmt.Println(block.Text) + } +} +``` + +**Key features of the Go tool runner:** + +- Automatic schema generation from Go structs via `jsonschema` tags +- `RunToCompletion()` for simple one-shot usage +- `All()` iterator for processing each message in the conversation +- `NextMessage()` for step-by-step iteration +- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()` + +### Manual Loop + +For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls. + +Derived from `anthropic-sdk-go/examples/tools/main.go`. + +```go +package main + +import ( + "context" + "encoding/json" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" +) + +func main() { + client := anthropic.NewClient() + + // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed. + addTool := anthropic.ToolParam{ + Name: "add", + Description: anthropic.String("Add two integers"), + InputSchema: anthropic.ToolInputSchemaParam{ + Properties: map[string]any{ + "a": map[string]any{"type": "integer"}, + "b": map[string]any{"type": "integer"}, + }, + }, + } + // ToolParam must be wrapped in ToolUnionParam for the Tools slice + tools := []anthropic.ToolUnionParam{{OfTool: &addTool}} + + messages := []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")), + } + + for { + resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Messages: messages, + Tools: tools, + }) + if err != nil { + log.Fatal(err) + } + + // 2. Append the assistant response to history BEFORE processing tool calls. + // resp.ToParam() converts Message → MessageParam in one call. + messages = append(messages, resp.ToParam()) + + // 3. Walk content blocks. ContentBlockUnion is a flattened struct; + // use block.AsAny().(type) to switch on the actual variant. + toolResults := []anthropic.ContentBlockParamUnion{} + for _, block := range resp.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + case anthropic.ToolUseBlock: + // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the + // raw JSON — block.Input is json.RawMessage, not the parsed value. + var in struct { + A int `json:"a"` + B int `json:"b"` + } + if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil { + log.Fatal(err) + } + result := fmt.Sprintf("%d", in.A+in.B) + // 5. NewToolResultBlock(toolUseID, content, isError) builds the + // ContentBlockParamUnion for you. block.ID is the tool_use_id. + toolResults = append(toolResults, + anthropic.NewToolResultBlock(block.ID, result, false)) + } + } + + // 6. Exit when Claude stops asking for tools + if resp.StopReason != anthropic.StopReasonToolUse { + break + } + + // 7. Tool results go in a user message (variadic: all results in one turn) + messages = append(messages, anthropic.NewUserMessage(toolResults...)) + } +} +``` + +**Key API surface:** + +| Symbol | Purpose | +|---|---| +| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history | +| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants | +| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) | +| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block | +| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn | +| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination | +| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` | + +--- + +## Thinking + +Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`. + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control. + +Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `NewThinkingConfigAdaptiveParam`). + +```go +// There is no ThinkingConfigParamOfAdaptive helper — construct the union +// struct-literal directly and take the address of the variant. +adaptive := anthropic.NewThinkingConfigAdaptiveParam() +params := anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive}, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")), + }, +} + +resp, err := client.Messages.New(context.Background(), params) +if err != nil { + log.Fatal(err) +} + +// ThinkingBlock(s) precede TextBlock in content +for _, block := range resp.Content { + switch b := block.AsAny().(type) { + case anthropic.ThinkingBlock: + fmt.Println("[thinking]", b.Thinking) + case anthropic.TextBlock: + fmt.Println(b.Text) + } +} +``` + +> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. + +--- + +## Prompt Caching + +`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```go +System: []anthropic.TextBlockParam{{ + Text: longSystemPrompt, + CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL +}}, +``` + +For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block. + +Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`. + +--- + +## Server-Side Tools + +Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field. + +```go +Tools: []anthropic.ToolUnionParam{ + {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}}, + {OfBashTool20250124: &anthropic.ToolBash20250124Param{}}, + {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}}, + {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}}, +}, +``` + +Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. + +--- + +## PDF / Document Input + +`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set. + +```go +b64 := base64.StdEncoding.EncodeToString(pdfBytes) + +msg := anthropic.NewUserMessage( + anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}), + anthropic.NewTextBlock("Summarize this document"), +) +``` + +Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`. + +--- + +## Files API (Beta) + +Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding. + +```go +f, _ := os.Open("./upload_me.txt") +defer f.Close() + +meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: anthropic.File(f, "upload_me.txt", "text/plain"), + Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14}, +}) +// meta.ID is the file_id to reference in subsequent message requests +``` + +Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`. + +--- + +## Context Editing / Compaction (Beta) + +Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip. + +```go +params := anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, // also supported: ModelClaudeSonnet4_6 + MaxTokens: 16000, + Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, + ContextManagement: anthropic.BetaContextManagementConfigParam{ + Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ + {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, + }, + }, + Messages: []anthropic.BetaMessageParam{ /* ... */ }, +} + +resp, err := client.Beta.Messages.New(ctx, params) +if err != nil { + log.Fatal(err) +} + +// Round-trip: append response to history via .ToParam() +params.Messages = append(params.Messages, resp.ToParam()) + +// Read compaction blocks from the response +for _, block := range resp.Content { + if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok { + fmt.Println("compaction summary:", c.Content) + } +} +``` + +Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`. diff --git a/junie/versions/2206.4/skills/claude-api/go/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/go/managed-agents/README.md new file mode 100644 index 0000000..e7b855f --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/go/managed-agents/README.md @@ -0,0 +1,561 @@ +# Managed Agents — Go + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Go. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Go SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "context" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) + +ctx := context.Background() +``` + +--- + +## Create an Environment + +```go +environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ + Name: "my-dev-env", + Config: anthropic.BetaCloudConfigParams{ + Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ + OfUnrestricted: &anthropic.UnrestrictedNetworkParam{}, + }, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(environment.ID) // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `Model`/`System`/`Tools` live on the agent object, not the session. Always start with `Beta.Agents.New()` — the session only takes `Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}` (or the typed `OfBetaManagedAgentsAgents` variant when you need a specific version). + +### Minimal + +```go +// 1. Create the agent (reusable, versioned) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "Coding Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + System: anthropic.String("You are a helpful coding assistant."), + Tools: []anthropic.BetaAgentNewParamsToolUnion{{ + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }}, +}) +if err != nil { + panic(err) +} + +// 2. Start a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + Title: anthropic.String("Quickstart session"), +}) +if err != nil { + panic(err) +} +fmt.Printf("Session ID: %s, status: %s\n", session.ID, session.Status) +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```go +updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ + Version: agent.Version, + System: anthropic.String("You are a helpful coding agent. Always write tests."), +}) +if err != nil { + panic(err) +} +fmt.Printf("New version: %d\n", updatedAgent.Version) + +// List all versions +iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{}) +for iter.Next() { + version := iter.Current() + fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339)) +} +if err := iter.Err(); err != nil { + panic(err) +} + +// Archive the agent +_, err = client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## Send a User Message + +```go +_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Review the auth module", + }, + }}, + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```go +// Open the stream first, then send the user message +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Summarize the repo README", + }, + }}, + }, + }}, +}); err != nil { + panic(err) +} + +events: +for stream.Next() { + switch event := stream.Current().AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsAgentToolUseEvent: + fmt.Printf("\n[Using tool: %s]\n", event.Name) + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break events + case anthropic.BetaManagedAgentsSessionErrorEvent: + fmt.Printf("\n[Error: %s]\n", event.Error.Message) + break events + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```go +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +// Stream is open and buffering. List history before tailing live. +seenEventIDs := map[string]struct{}{} +history := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for history.Next() { + seenEventIDs[history.Current().ID] = struct{}{} +} +if err := history.Err(); err != nil { + panic(err) +} + +// Tail live events, skipping anything already seen +tail: +for stream.Next() { + event := stream.Current() + if _, seen := seenEventIDs[event.ID]; seen { + continue + } + seenEventIDs[event.ID] = struct{}{} + switch event := event.AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break tail + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Go managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `github.com/anthropics/anthropic-sdk-go` repository for the corresponding Go params types. + +--- + +## Poll Events + +```go +// Auto-paginating iterator +iter := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for iter.Next() { + event := iter.Current() + fmt.Printf("%s: %s\n", event.Type, event.ID) +} +if err := iter.Err(); err != nil { + panic(err) +} +``` + +--- + +## Upload a File + +```go +csvFile, err := os.Open("data.csv") +if err != nil { + panic(err) +} +defer csvFile.Close() + +file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: csvFile, +}) +if err != nil { + panic(err) +} +fmt.Printf("File ID: %s\n", file.ID) + +// Mount in a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String(agent.ID), + }, + EnvironmentID: environment.ID, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{{ + OfFile: &anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + MountPath: anthropic.String("/workspace/data.csv"), + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +### Add and Manage Resources on an Existing Session + +```go +// Attach an additional file to an open session +resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(resource.ID) // "sesrsc_01ABC..." + +// List resources on the session +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +for _, entry := range listed.Data { + fmt.Println(entry.ID, entry.Type) +} + +// Detach a resource +if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{ + SessionID: session.ID, +}); err != nil { + panic(err) +} +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Go in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `github.com/anthropics/anthropic-sdk-go` repository for the `Beta.Files.List` and `Beta.Files.Download` Go params types. + +--- + +## Session Management + +```go +// List environments +environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{}) +if err != nil { + panic(err) +} + +// Retrieve a specific environment +env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{}) +if err != nil { + panic(err) +} + +// Archive an environment (read-only, existing sessions continue) +_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{}) +if err != nil { + panic(err) +} + +// Delete an environment (only if no sessions reference it) +_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{}) +if err != nil { + panic(err) +} + +// Delete a session +_, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## MCP Server Integration + +```go +// Agent declares MCP server (no auth here — auth goes in a vault) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "GitHub Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + MCPServers: []anthropic.BetaManagedAgentsUrlmcpServerParams{{ + Type: anthropic.BetaManagedAgentsUrlmcpServerParamsTypeURL, + Name: "github", + URL: "https://api.githubcopilot.com/mcp/", + }}, + Tools: []anthropic.BetaAgentNewParamsToolUnion{ + { + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }, + { + OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ + Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, + MCPServerName: "github", + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Session attaches vault(s) containing credentials for those MCP server URLs +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, +}) +if err != nil { + panic(err) +} +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```go +// Create a vault +vault, err := client.Beta.Vaults.New(ctx, anthropic.BetaVaultNewParams{ + DisplayName: "Alice", + Metadata: map[string]string{"external_user_id": "usr_abc123"}, +}) +if err != nil { + panic(err) +} + +// Add an OAuth credential +credential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{ + DisplayName: anthropic.String("Alice's Slack"), + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthCreateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth, + MCPServerURL: "https://mcp.slack.com/mcp", + AccessToken: "xoxp-...", + ExpiresAt: anthropic.Time(time.Date(2026, time.April, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshParams{ + TokenEndpoint: "https://slack.com/api/oauth.v2.access", + ClientID: "1234567890.0987654321", + Scope: anthropic.String("channels:read chat:write"), + RefreshToken: "xoxe-1-...", + TokenEndpointAuth: anthropic.BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnion{ + OfClientSecretPost: &anthropic.BetaManagedAgentsTokenEndpointAuthPostParam{ + Type: anthropic.BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost, + ClientSecret: "abc123...", + }, + }, + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Rotate the credential (e.g., after a token refresh) +_, err = client.Beta.Vaults.Credentials.Update(ctx, credential.ID, anthropic.BetaVaultCredentialUpdateParams{ + VaultID: vault.ID, + Auth: anthropic.BetaVaultCredentialUpdateParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthUpdateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth, + AccessToken: anthropic.String("xoxp-new-..."), + ExpiresAt: anthropic.Time(time.Date(2026, time.May, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshUpdateParams{ + RefreshToken: anthropic.String("xoxe-1-new-..."), + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Archive a vault +_, err = client.Beta.Vaults.Archive(ctx, vault.ID, anthropic.BetaVaultArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```go +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/repo", + MountPath: anthropic.String("/workspace/repo"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + }, +}) +if err != nil { + panic(err) +} +``` + +Multiple repositories on the same session: + +```go +resources := []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/frontend", + MountPath: anthropic.String("/workspace/frontend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/backend", + MountPath: anthropic.String("/workspace/backend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, +} +``` + +Rotating a repository's authorization token: + +```go +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +repoResourceID := listed.Data[0].ID + +_, err = client.Beta.Sessions.Resources.Update(ctx, repoResourceID, anthropic.BetaSessionResourceUpdateParams{ + SessionID: session.ID, + AuthorizationToken: "ghp_your_new_github_token", +}) +if err != nil { + panic(err) +} +``` diff --git a/junie/versions/2206.4/skills/claude-api/java/claude-api.md b/junie/versions/2206.4/skills/claude-api/java/claude-api.md new file mode 100644 index 0000000..22f872e --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/java/claude-api.md @@ -0,0 +1,432 @@ +# Claude API — Java + +> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java. + +## Installation + +Maven: + +```xml + + com.anthropic + anthropic-java + 2.17.0 + +``` + +Gradle: + +```groovy +implementation("com.anthropic:anthropic-java:2.17.0") +``` + +## Client Initialization + +```java +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (reads ANTHROPIC_API_KEY from environment) +AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + +// Explicit API key +AnthropicClient client = AnthropicOkHttpClient.builder() + .apiKey("your-api-key") + .build(); +``` + +--- + +## Basic Message Request + +```java +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Message; +import com.anthropic.models.messages.Model; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addUserMessage("What is the capital of France?") + .build(); + +Message response = client.messages().create(params); +response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> System.out.println(textBlock.text())); +``` + +--- + +## Streaming + +```java +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.messages.RawMessageStreamEvent; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(64000L) + .addUserMessage("Write a haiku") + .build(); + +try (StreamResponse streamResponse = client.messages().createStreaming(params)) { + streamResponse.stream() + .flatMap(event -> event.contentBlockDelta().stream()) + .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) + .forEach(textDelta -> System.out.print(textDelta.text())); +} +``` + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping. + +```java +import com.anthropic.models.messages.ContentBlock; +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Model; +import com.anthropic.models.messages.ThinkingConfigAdaptive; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .addUserMessage("Solve this step by step: 27 * 453") + .build(); + +for (ContentBlock block : client.messages().create(params).content()) { + block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking())); + block.text().ifPresent(t -> System.out.println(t.text())); +} +``` + +> **Deprecated:** `ThinkingConfigEnabled.builder().budgetTokens(N)` (and the `.enabledThinking(N)` shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant). + +--- + +## Tool Use (Beta) + +The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier` for automatic execution via `BetaToolRunner`. + +### Tool Runner (automatic loop) + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.helpers.BetaToolRunner; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; +import java.util.function.Supplier; + +@JsonClassDescription("Get the weather in a given location") +static class GetWeather implements Supplier { + @JsonPropertyDescription("The city and state, e.g. San Francisco, CA") + public String location; + + @Override + public String get() { + return "The weather in " + location + " is sunny and 72°F"; + } +} + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(16000L) + .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13") + .addTool(GetWeather.class) + .addUserMessage("What's the weather in San Francisco?") + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +### Memory Tool + +The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically. + +```java +import com.anthropic.helpers.BetaMemoryToolHandler; +import com.anthropic.helpers.BetaToolRunner; +import com.anthropic.models.beta.messages.BetaMemoryTool20250818; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.ToolRunnerCreateParams; + +// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem) +BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot); + +MessageCreateParams createParams = MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(4096L) + .addTool(BetaMemoryTool20250818.builder().build()) + .addUserMessage("Remember that my favorite color is blue") + .build(); + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + ToolRunnerCreateParams.builder() + .betaMemoryToolHandler(memoryHandler) + .initialMessageParams(createParams) + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +See the [shared memory tool concepts](../shared/tool-use-concepts.md) for more details on the memory tool. + +### Non-Beta Tool Declaration (manual JSON schema) + +`Tool.InputSchema.Properties` is a freeform `Map` wrapper — build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically. + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.messages.Tool; + +Tool tool = Tool.builder() + .name("get_weather") + .description("Get the current weather in a given location") + .inputSchema(Tool.InputSchema.builder() + .properties(Tool.InputSchema.Properties.builder() + .putAdditionalProperty("location", JsonValue.from(Map.of("type", "string"))) + .build()) + .required(List.of("location")) + .build()) + .build(); + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .addTool(tool) + .addUserMessage("Weather in Paris?") + .build(); +``` + +For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../shared/tool-use-concepts.md). + +### Building `MessageParam` with Content Blocks (Tool Result Round-Trip) + +`MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List)` alias — there is NO separate `MessageParamContent` class with a static `ofBlockParams`: + +```java +import com.anthropic.models.messages.MessageParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.ToolResultBlockParam; + +List results = List.of( + ContentBlockParam.ofToolResult(ToolResultBlockParam.builder() + .toolUseId(toolUseBlock.id()) + .content(yourResultString) + .build()) +); + +MessageParam toolResultMsg = MessageParam.builder() + .role(MessageParam.Role.USER) + .contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...) + .build(); +``` + +--- + +## Effort Parameter + +Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`. + +```java +import com.anthropic.models.messages.OutputConfig; + +.outputConfig(OutputConfig.builder() + .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX + .build()) +``` + +Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control. + +--- + +## Prompt Caching + +System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```java +import com.anthropic.models.messages.TextBlockParam; +import com.anthropic.models.messages.CacheControlEphemeral; + +.systemOfTextBlockParams(List.of( + TextBlockParam.builder() + .text(longSystemPrompt) + .cacheControl(CacheControlEphemeral.builder() + .ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M + .build()) + .build())) +``` + +There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`. + +Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`. + +--- + +## Token Counting + +```java +import com.anthropic.models.messages.MessageCountTokensParams; + +long tokens = client.messages().countTokens( + MessageCountTokensParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .addUserMessage("Hello") + .build() +).inputTokens(); +``` + +--- + +## Structured Output + +The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing. + +```java +import com.anthropic.models.messages.StructuredMessageCreateParams; + +record Book(String title, String author) {} +record BookList(List books) {} + +StructuredMessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .outputConfig(BookList.class) // returns a typed builder + .addUserMessage("List 3 classic novels") + .build(); + +client.messages().create(params).content().stream() + .flatMap(cb -> cb.text().stream()) + .forEach(typed -> { + // typed.text() returns BookList, not String + for (Book b : typed.text().books()) System.out.println(b.title()); + }); +``` + +Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`. + +```java +import com.anthropic.models.messages.DocumentBlockParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.TextBlockParam; + +DocumentBlockParam doc = DocumentBlockParam.builder() + .base64Source(base64String) // or .urlSource("https://...") or .textSource("...") + .title("My Document") // optional + .build(); + +.addUserMessageOfBlockParams(List.of( + ContentBlockParam.ofDocument(doc), + ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build()))) +``` + +--- + +## Server-Side Tools + +Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for every type — no manual `ToolUnion` wrapping. + +```java +import com.anthropic.models.messages.WebSearchTool20260209; +import com.anthropic.models.messages.ToolBash20250124; +import com.anthropic.models.messages.ToolTextEditor20250728; +import com.anthropic.models.messages.CodeExecutionTool20260120; + +.addTool(WebSearchTool20260209.builder() + .maxUses(5L) // optional + .allowedDomains(List.of("example.com")) // optional + .build()) +.addTool(ToolBash20250124.builder().build()) +.addTool(ToolTextEditor20250728.builder().build()) +.addTool(CodeExecutionTool20260120.builder().build()) +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. + +### Beta namespace (MCP, compaction) + +For beta-only features use `com.anthropic.models.beta.messages.*` — class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`: + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaToolBash20250124; +import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120; +import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addBeta("mcp-client-2025-11-20") + .addTool(BetaToolBash20250124.builder().build()) + .addTool(BetaCodeExecutionTool20260120.builder().build()) + .addMcpServer(BetaRequestMcpServerUrlDefinition.builder() + .name("my-server") + .url("https://example.com/mcp") + .build()) + .addUserMessage("...") + .build(); + +client.beta().messages().create(params); +``` + +`BetaTool*` types are NOT interchangeable with non-beta `Tool*` — pick one namespace per request. + +**Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` — there is NO typed `.input()`. For code execution results, unwrap two levels: + +```java +for (ContentBlock block : response.content()) { + block.serverToolUse().ifPresent(stu -> { + System.out.println("tool: " + stu.name() + " input: " + stu._input()); + }); + block.codeExecutionToolResult().ifPresent(r -> { + r.content().resultBlock().ifPresent(result -> { + System.out.println("stdout: " + result.stdout()); + System.out.println("stderr: " + result.stderr()); + System.out.println("exit: " + result.returnCode()); + }); + }); +} +``` + +--- + +## Files API (Beta) + +Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant). + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.files.FileMetadata; +import com.anthropic.models.beta.messages.BetaRequestDocumentBlock; +import java.nio.file.Paths; + +FileMetadata meta = client.beta().files().upload( + FileUploadParams.builder() + .file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[]) + .build()); + +// Reference in a beta message: +BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder() + .fileSource(meta.id()) + .build(); +``` + +Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`. diff --git a/junie/versions/2206.4/skills/claude-api/java/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/java/managed-agents/README.md new file mode 100644 index 0000000..49398bc --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/java/managed-agents/README.md @@ -0,0 +1,442 @@ +# Managed Agents — Java + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Java. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Java SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```xml + + com.anthropic + anthropic-java + +``` + +## Client Initialization + +```java +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (uses ANTHROPIC_API_KEY env var) +var client = AnthropicOkHttpClient.fromEnv(); +``` + +--- + +## Create an Environment + +```java +import com.anthropic.models.beta.environments.BetaCloudConfigParams; +import com.anthropic.models.beta.environments.EnvironmentCreateParams; +import com.anthropic.models.beta.environments.UnrestrictedNetwork; + +var environment = client.beta().environments().create(EnvironmentCreateParams.builder() + .name("my-dev-env") + .config(BetaCloudConfigParams.builder() + .networking(UnrestrictedNetwork.builder().build()) + .build()) + .build()); +System.out.println("Environment ID: " + environment.id()); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Model, system, and tools live on the agent object, not the session. Always start with `client.beta().agents().create()` — the session takes either `.agent(agent.id())` or the typed `BetaManagedAgentsAgentParams.builder()...build()`. + +### Minimal + +```java +import com.anthropic.models.beta.agents.AgentCreateParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params; +import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams; +import com.anthropic.models.beta.sessions.SessionCreateParams; + +// 1. Create the agent (reusable, versioned) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("Coding Assistant") + .model("claude-opus-4-6") + .system("You are a helpful coding assistant.") + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .build()); + +// 2. Start a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .title("Quickstart session") + .build()); +System.out.println("Session ID: " + session.id()); +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```java +import com.anthropic.models.beta.agents.AgentUpdateParams; + +var updatedAgent = client.beta().agents().update(agent.id(), AgentUpdateParams.builder() + .version(agent.version()) + .system("You are a helpful coding agent. Always write tests.") + .build()); +System.out.println("New version: " + updatedAgent.version()); + +// List all versions +for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) { + System.out.println("Version " + version.version() + ": " + version.updatedAt()); +} + +// Archive the agent +var archived = client.beta().agents().archive(agent.id()); +System.out.println("Archived at: " + archived.archivedAt().orElseThrow()); +``` + +--- + +## Send a User Message + +```java +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; + +client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Review the auth module") + .build()) + .build()); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```java +import com.anthropic.models.beta.sessions.events.StreamEvents; + +// Open the stream first, then send the user message +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Summarize the repo README") + .build()) + .build()); + + for (var event : (Iterable) stream.stream()::iterator) { + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isAgentToolUse()) { + System.out.println("\n[Using tool: " + event.asAgentToolUse().name() + "]"); + } else if (event.isSessionStatusIdle()) { + break; + } else if (event.isSessionError()) { + System.out.println("\n[Error]"); + break; + } + } +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events. The cross-variant `id` field is read from the raw `_json()` value: + +```java +import com.anthropic.core.JsonValue; +import java.util.HashSet; +import java.util.Map; +import java.util.Optional; + +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + // Stream is open and buffering. List history before tailing live. + var seenEventIds = new HashSet(); + for (var past : client.beta().sessions().events().list(session.id()).autoPager()) { + Optional> obj = past._json().orElseThrow().asObject(); + seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow()); + } + + // Tail live events, skipping anything already seen + for (var event : (Iterable) stream.stream()::iterator) { + Optional> obj = event._json().orElseThrow().asObject(); + if (!seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow())) continue; + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isSessionStatusIdle()) { + break; + } + } +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Java managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-java` repository for the corresponding params types. + +--- + +## Poll Events + +```java +for (var event : client.beta().sessions().events().list(session.id()).autoPager()) { + System.out.println(event.type() + ": " + event); +} +``` + +--- + +## Upload a File + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import java.nio.file.Path; + +var dataCsv = Path.of("data.csv"); + +var file = client.beta().files().upload(FileUploadParams.builder() + .file(dataCsv) + .build()); +System.out.println("File ID: " + file.id()); + +// Mount in a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addResource(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .mountPath("/workspace/data.csv") + .build()) + .build()); +``` + +### Add and Manage Resources on an Existing Session + +```java +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +// Attach an additional file to an open session +var resource = client.beta().sessions().resources().add(session.id(), ResourceAddParams.builder() + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .build()) + .build()); +System.out.println(resource.id()); // "sesrsc_01ABC..." + +// List resources on the session — entries are a discriminated union +var listed = client.beta().sessions().resources().list(session.id()); +for (var entry : listed.data()) { + if (entry.isFile()) { + var fileResource = entry.asFile(); + System.out.println(fileResource.id() + " " + fileResource.type()); + } else if (entry.isGitHubRepository()) { + var repoResource = entry.asGitHubRepository(); + System.out.println(repoResource.id() + " " + repoResource.type()); + } +} + +// Detach a resource +client.beta().sessions().resources().delete(resource.id(), ResourceDeleteParams.builder() + .sessionId(session.id()) + .build()); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Java in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-java` repository for the file list/download bindings. + +--- + +## Session Management + +```java +// List environments +var environments = client.beta().environments().list(); + +// Retrieve a specific environment +var env = client.beta().environments().retrieve(environment.id()); + +// Archive an environment (read-only, existing sessions continue) +client.beta().environments().archive(environment.id()); + +// Delete an environment (only if no sessions reference it) +client.beta().environments().delete(environment.id()); + +// Delete a session +client.beta().sessions().delete(session.id()); +``` + +--- + +## MCP Server Integration + +```java +import com.anthropic.models.beta.agents.BetaManagedAgentsMcpToolsetParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsUrlmcpServerParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("GitHub Assistant") + .model("claude-opus-4-6") + .addMcpServer(BetaManagedAgentsUrlmcpServerParams.builder() + .type(BetaManagedAgentsUrlmcpServerParams.Type.URL) + .name("github") + .url("https://api.githubcopilot.com/mcp/") + .build()) + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .addTool(BetaManagedAgentsMcpToolsetParams.builder() + .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) + .mcpServerName("github") + .build()) + .build()); + +// Session attaches vault(s) containing credentials for those MCP server URLs +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .build()); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.beta.vaults.VaultCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshUpdateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthUpdateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; +import java.time.OffsetDateTime; + +// Create a vault +var vault = client.beta().vaults().create(VaultCreateParams.builder() + .displayName("Alice") + .metadata(VaultCreateParams.Metadata.builder() + .putAdditionalProperty("external_user_id", JsonValue.from("usr_abc123")) + .build()) + .build()); +System.out.println(vault.id()); // "vlt_01ABC..." + +// Add an OAuth credential +var credential = client.beta().vaults().credentials().create(vault.id(), + CredentialCreateParams.builder() + .displayName("Alice's Slack") + .auth(BetaManagedAgentsMcpOAuthCreateParams.builder() + .type(BetaManagedAgentsMcpOAuthCreateParams.Type.MCP_OAUTH) + .mcpServerUrl("https://mcp.slack.com/mcp") + .accessToken("xoxp-...") + .expiresAt(OffsetDateTime.parse("2026-04-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshParams.builder() + .tokenEndpoint("https://slack.com/api/oauth.v2.access") + .clientId("1234567890.0987654321") + .scope("channels:read chat:write") + .refreshToken("xoxe-1-...") + .clientSecretPostTokenEndpointAuth("abc123...") + .build()) + .build()) + .build()); + +// Rotate the credential (e.g., after a token refresh) +client.beta().vaults().credentials().update(credential.id(), + CredentialUpdateParams.builder() + .vaultId(vault.id()) + .auth(BetaManagedAgentsMcpOAuthUpdateParams.builder() + .type(BetaManagedAgentsMcpOAuthUpdateParams.Type.MCP_OAUTH) + .accessToken("xoxp-new-...") + .expiresAt(OffsetDateTime.parse("2026-05-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshUpdateParams.builder() + .refreshToken("xoxe-1-new-...") + .build()) + .build()) + .build()); + +// Archive a vault +client.beta().vaults().archive(vault.id()); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```java +import com.anthropic.models.beta.sessions.BetaManagedAgentsGitHubRepositoryResourceParams; + +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/repo") + .mountPath("/workspace/repo") + .authorizationToken("ghp_your_github_token") + .build()) + .build()); +``` + +Multiple repositories on the same session: + +```java +import java.util.List; + +var resources = List.of( + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/frontend") + .mountPath("/workspace/frontend") + .authorizationToken("ghp_your_github_token") + .build(), + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/backend") + .mountPath("/workspace/backend") + .authorizationToken("ghp_your_github_token") + .build()); +``` + +Rotating a repository's authorization token: + +```java +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; + +var listed = client.beta().sessions().resources().list(session.id()); +var repoResourceId = listed.data().get(0).asGitHubRepository().id(); + +client.beta().sessions().resources().update(repoResourceId, ResourceUpdateParams.builder() + .sessionId(session.id()) + .authorizationToken("ghp_your_new_github_token") + .build()); +``` diff --git a/junie/versions/2206.4/skills/claude-api/php/claude-api.md b/junie/versions/2206.4/skills/claude-api/php/claude-api.md new file mode 100644 index 0000000..cec5ead --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/php/claude-api.md @@ -0,0 +1,375 @@ +# Claude API — PHP + +> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Using API key from environment variable +$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY")); +``` + +### Amazon Bedrock + +```php +use Anthropic\Bedrock; + +// Constructor is private — use the static factory. Reads AWS credentials from env. +$client = Bedrock\Client::fromEnvironment(region: 'us-east-1'); +``` + +### Google Vertex AI + +```php +use Anthropic\Vertex; + +// Constructor is private. Parameter is `location`, not `region`. +$client = Vertex\Client::fromEnvironment( + location: 'us-east5', + projectId: 'my-project-id', +); +``` + +### Anthropic Foundry + +```php +use Anthropic\Foundry; + +// Constructor is private. baseUrl or resource is required. +$client = Foundry\Client::withCredentials( + authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'), + baseUrl: 'https://.services.ai.azure.com/anthropic', +); +``` + +--- + +## Basic Message Request + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [ + ['role' => 'user', 'content' => 'What is the capital of France?'], + ], +); + +// content is an array of polymorphic blocks (TextBlock, ToolUseBlock, +// ThinkingBlock). Accessing ->text on content[0] without checking the block +// type will throw if the first block is not a TextBlock (e.g., when extended +// thinking is enabled and a ThinkingBlock comes first). Always guard: +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +If you only want the first text block: + +```php +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + break; + } +} +``` + +--- + +## Streaming + +> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"` + +```php +use Anthropic\Messages\RawContentBlockDeltaEvent; +use Anthropic\Messages\TextDelta; + +$stream = $client->messages->createStream( + model: 'claude-opus-4-6', + maxTokens: 64000, + messages: [ + ['role' => 'user', 'content' => 'Write a haiku'], + ], +); + +foreach ($stream as $event) { + if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) { + echo $event->delta->text; + } +} +``` + +--- + +## Tool Use + +### Tool Runner (Beta) + +**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure: + +```php +use Anthropic\Lib\Tools\BetaRunnableTool; + +$weatherTool = new BetaRunnableTool( + definition: [ + 'name' => 'get_weather', + 'description' => 'Get the current weather for a location.', + 'input_schema' => [ + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], + run: function (array $input): string { + return "The weather in {$input['location']} is sunny and 72°F."; + }, +); + +$runner = $client->beta->messages->toolRunner( + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']], + model: 'claude-opus-4-6', + tools: [$weatherTool], +); + +foreach ($runner as $message) { + foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } + } +} +``` + +### Manual Loop + +Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. + +```php +use Anthropic\Messages\ToolUseBlock; + +$tools = [ + [ + 'name' => 'get_weather', + 'description' => 'Get the current weather in a given location', + 'inputSchema' => [ // camelCase, not input_schema + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], +]; + +$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']]; + +$response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, +); + +while ($response->stopReason === 'tool_use') { // camelCase property + $toolResults = []; + foreach ($response->content as $block) { + if ($block instanceof ToolUseBlock) { + // $block->name : string — tool name to dispatch on + // $block->input : array — parsed JSON input + // $block->id : string — pass back as toolUseID + $result = executeYourTool($block->name, $block->input); + $toolResults[] = [ + 'type' => 'tool_result', + 'toolUseID' => $block->id, // camelCase, not tool_use_id + 'content' => $result, + ]; + } + } + + // Append assistant turn + user turn with tool results + $messages[] = ['role' => 'assistant', 'content' => $response->content]; + $messages[] = ['role' => 'user', 'content' => $toolResults]; + + $response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, + ); +} + +// Final text response +foreach ($response->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan. + + +--- + +## Extended Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```php +use Anthropic\Messages\ThinkingBlock; + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + thinking: ['type' => 'adaptive'], + messages: [ + ['role' => 'user', 'content' => 'Solve: 27 * 453'], + ], +); + +// ThinkingBlock(s) precede TextBlock in content +foreach ($message->content as $block) { + if ($block instanceof ThinkingBlock) { + echo "Thinking:\n{$block->thinking}\n\n"; + // $block->signature is an opaque string — preserve verbatim if + // passing thinking blocks back in multi-turn conversations + } elseif ($block->type === 'text') { + echo "Answer: {$block->text}\n"; + } +} +``` + +> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan. + +--- + +## Prompt Caching + +`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + system: [ + ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']], + ], + messages: [['role' => 'user', 'content' => 'Summarize the key points']], +); +``` + +For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block. + +Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`. + +--- + +## Structured Outputs + +### Using StructuredOutputModel (Recommended) + +Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`: + +```php +use Anthropic\Lib\Contracts\StructuredOutputModel; +use Anthropic\Lib\Concerns\StructuredOutputModelTrait; +use Anthropic\Lib\Attributes\Constrained; + +class Person implements StructuredOutputModel +{ + use StructuredOutputModelTrait; + + #[Constrained(description: 'Full name')] + public string $name; + + public int $age; + + public ?string $email = null; // nullable = optional field +} + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']], + outputConfig: ['format' => Person::class], +); + +$person = $message->parsedOutput(); // Person instance +echo $person->name; +``` + +Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields. + +### Raw Schema + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']], + outputConfig: [ + 'format' => [ + 'type' => 'json_schema', + 'schema' => [ + 'type' => 'object', + 'properties' => [ + 'name' => ['type' => 'string'], + 'email' => ['type' => 'string'], + 'plan' => ['type' => 'string'], + ], + 'required' => ['name', 'email', 'plan'], + 'additionalProperties' => false, + ], + ], + ], +); + +// First text block contains valid JSON +foreach ($message->content as $block) { + if ($block->type === 'text') { + $data = json_decode($block->text, true); + break; + } +} +``` + +--- + +## Beta Features & Server-Side Tools + +**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header: + +```php +use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition; + +$response = $client->beta->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + mcpServers: [ + BetaRequestMCPServerURLDefinition::with( + name: 'my-server', + url: 'https://example.com/mcp', + ), + ], + betas: ['mcp-client-2025-11-20'], // only valid on ->beta->messages + messages: [['role' => 'user', 'content' => 'Use the MCP tools']], +); +``` + +**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these. diff --git a/junie/versions/2206.4/skills/claude-api/php/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/php/managed-agents/README.md new file mode 100644 index 0000000..1c8673c --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/php/managed-agents/README.md @@ -0,0 +1,435 @@ +# Managed Agents — PHP + +> **Bindings not shown here:** This README covers the most common managed-agents flows for PHP. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the PHP SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Default (uses ANTHROPIC_API_KEY env var) +$client = new Client(); + +// Explicit API key +$client = new Client(apiKey: 'your-api-key'); +``` + +--- + +## Create an Environment + +```php +$environment = $client->beta->environments->create( + name: 'my-dev-env', + config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']], +); +echo "Environment ID: {$environment->id}\n"; // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `$client->beta->agents->create()` — the session takes either `agent: $agent->id` or the typed `BetaManagedAgentsAgentParams::with(type: 'agent', id: $agent->id, version: $agent->version)`. + +### Minimal + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; + +// 1. Create the agent (reusable, versioned) +$agent = $client->beta->agents->create( + name: 'Coding Assistant', + model: 'claude-opus-4-6', + system: 'You are a helpful coding assistant.', + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with( + type: 'agent_toolset_20260401', + ), + ], +); + +// 2. Start a session +$session = $client->beta->sessions->create( + agent: ['type' => 'agent', 'id' => $agent->id, 'version' => $agent->version], + environmentID: $environment->id, + title: 'Quickstart session', +); +echo "Session ID: {$session->id}\n"; +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```php +$updatedAgent = $client->beta->agents->update( + $agent->id, + version: $agent->version, + system: 'You are a helpful coding agent. Always write tests.', +); +echo "New version: {$updatedAgent->version}\n"; + +// List all versions +foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) { + echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n"; +} + +// Archive the agent +$archived = $client->beta->agents->archive($agent->id); +echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n"; +``` + +--- + +## Send a User Message + +```php +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Review the auth module']], + ], + ], +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +> ℹ️ **Streaming transporter:** PHP's default buffered PSR-18 client never returns for the open-ended session event stream. Use a streaming Guzzle transporter for `streamStream()` calls — other calls keep the default client. + +```php +$streamingClient = new GuzzleHttp\Client(['stream' => true]); + +// Open the stream first, then send the user message +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Summarize the repo README']], + ], + ], +); + +foreach ($stream as $event) { + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + 'agent.tool_use' => print("\n[Using tool: {$event->name}]\n"), + 'session.error' => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'), + default => null, + }; + if ($event->type === 'session.status_idle' || $event->type === 'session.error') { + break; + } +} +$stream->close(); +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```php +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); + +// Stream is open and buffering. List history before tailing live. +$seenEventIds = []; +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + $seenEventIds[$event->id] = true; +} + +// Tail live events, skipping anything already seen +foreach ($stream as $event) { + if (isset($seenEventIds[$event->id])) { + continue; + } + $seenEventIds[$event->id] = true; + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + default => null, + }; + if ($event->type === 'session.status_idle') { + break; + } +} +$stream->close(); +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The PHP managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-ai/sdk` PHP repository for the corresponding params. + +--- + +## Poll Events + +```php +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + echo "{$event->type}: {$event->id}\n"; +} +``` + +--- + +## Upload a File + +> ℹ️ **PHP file upload:** The PHP SDK's beta managed-agents file upload binding is not shown in the apps source examples; the canonical PHP example uses raw cURL against `POST /v1/files`. If your codebase prefers the SDK, WebFetch the `anthropic-ai/sdk` PHP repository for the latest binding before writing code. + +```php +use Anthropic\Beta\Sessions\BetaManagedAgentsFileResourceParams; + +// Raw cURL upload (canonical example from the apps source) +$csvPath = 'data.csv'; +$ch = curl_init('https://api.anthropic.com/v1/files'); +curl_setopt_array($ch, [ + CURLOPT_RETURNTRANSFER => true, + CURLOPT_POST => true, + CURLOPT_HTTPHEADER => [ + 'x-api-key: ' . getenv('ANTHROPIC_API_KEY'), + 'anthropic-version: 2023-06-01', + 'anthropic-beta: files-api-2025-04-14', + ], + CURLOPT_POSTFIELDS => ['file' => new CURLFile($csvPath, 'text/csv', 'data.csv')], +]); +$file = json_decode(curl_exec($ch)); +echo "File ID: {$file->id}\n"; + +// Mount in a session +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + resources: [ + BetaManagedAgentsFileResourceParams::with( + type: 'file', + fileID: $file->id, + mountPath: '/workspace/data.csv', + ), + ], +); +``` + +### Add and Manage Resources on an Existing Session + +```php +// Attach an additional file to an open session +$resource = $client->beta->sessions->resources->add( + $session->id, + type: 'file', + fileID: $file->id, +); +echo "{$resource->id}\n"; // "sesrsc_01ABC..." + +// List resources on the session +$listed = $client->beta->sessions->resources->list($session->id); +foreach ($listed->data as $entry) { + echo "{$entry->id} {$entry->type}\n"; +} + +// Detach a resource +$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for PHP in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-ai/sdk` PHP repository for the file list/download bindings. + +--- + +## Session Management + +```php +// List environments +$environments = $client->beta->environments->list(); + +// Retrieve a specific environment +$env = $client->beta->environments->retrieve($environment->id); + +// Archive an environment (read-only, existing sessions continue) +$client->beta->environments->archive($environment->id); + +// Delete an environment (only if no sessions reference it) +$client->beta->environments->delete($environment->id); + +// Delete a session +$client->beta->sessions->delete($session->id); +``` + +--- + +## MCP Server Integration + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; +use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams; +use Anthropic\Beta\Agents\BetaManagedAgentsUrlmcpServerParams; +use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +$agent = $client->beta->agents->create( + name: 'GitHub Assistant', + model: 'claude-opus-4-6', + mcpServers: [ + BetaManagedAgentsUrlmcpServerParams::with( + type: 'url', + name: 'github', + url: 'https://api.githubcopilot.com/mcp/', + ), + ], + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'), + BetaManagedAgentsMCPToolsetParams::with( + type: 'mcp_toolset', + mcpServerName: 'github', + ), + ], +); + +// Session attaches vault(s) containing credentials for those MCP server URLs +$session = $client->beta->sessions->create( + agent: BetaManagedAgentsAgentParams::with( + type: 'agent', + id: $agent->id, + version: $agent->version, + ), + environmentID: $environment->id, + vaultIDs: [$vault->id], +); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```php +// Create a vault +$vault = $client->beta->vaults->create( + displayName: 'Alice', + metadata: ['external_user_id' => 'usr_abc123'], +); +echo $vault->id . "\n"; // "vlt_01ABC..." + +// Add an OAuth credential +$credential = $client->beta->vaults->credentials->create( + vaultID: $vault->id, + displayName: "Alice's Slack", + auth: [ + 'type' => 'mcp_oauth', + 'mcp_server_url' => 'https://mcp.slack.com/mcp', + 'access_token' => 'xoxp-...', + 'expires_at' => '2026-04-15T00:00:00Z', + 'refresh' => [ + 'token_endpoint' => 'https://slack.com/api/oauth.v2.access', + 'client_id' => '1234567890.0987654321', + 'scope' => 'channels:read chat:write', + 'refresh_token' => 'xoxe-1-...', + 'token_endpoint_auth' => [ + 'type' => 'client_secret_post', + 'client_secret' => 'abc123...', + ], + ], + ], +); + +// Rotate the credential (e.g., after a token refresh) +$client->beta->vaults->credentials->update( + $credential->id, + vaultID: $vault->id, + auth: [ + 'type' => 'mcp_oauth', + 'access_token' => 'xoxp-new-...', + 'expires_at' => '2026-05-15T00:00:00Z', + 'refresh' => ['refresh_token' => 'xoxe-1-new-...'], + ], +); + +// Archive a vault +$client->beta->vaults->archive($vault->id); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```php +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + vaultIDs: [$vault->id], + resources: [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/repo', + 'mountPath' => '/workspace/repo', + 'authorizationToken' => 'ghp_your_github_token', + ], + ], +); +``` + +Multiple repositories on the same session: + +```php +$resources = [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/frontend', + 'mountPath' => '/workspace/frontend', + 'authorizationToken' => 'ghp_your_github_token', + ], + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/backend', + 'mountPath' => '/workspace/backend', + 'authorizationToken' => 'ghp_your_github_token', + ], +]; +``` + +Rotating a repository's authorization token: + +```php +$listed = $client->beta->sessions->resources->list($session->id); +$repoResourceId = $listed->data[0]->id; + +$client->beta->sessions->resources->update( + $repoResourceId, + sessionID: $session->id, + authorizationToken: 'ghp_your_new_github_token', +); +``` diff --git a/junie/versions/2206.4/skills/claude-api/python/claude-api/README.md b/junie/versions/2206.4/skills/claude-api/python/claude-api/README.md new file mode 100644 index 0000000..c2acc35 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/claude-api/README.md @@ -0,0 +1,420 @@ +# Claude API — Python + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") + +# Async client +async_client = anthropic.AsyncAnthropic() +``` + +--- + +## Basic Message Request + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[ + {"role": "user", "content": "What is the capital of France?"} + ] +) +# response.content is a list of content block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). Check .type before accessing .text. +for block in response.content: + if block.type == "text": + print(block.text) +``` + +--- + +## System Prompts + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system="You are a helpful coding assistant. Always provide examples in Python.", + messages=[{"role": "user", "content": "How do I read a JSON file?"}] +) +``` + +--- + +## Vision (Images) + +### Base64 + +```python +import base64 + +with open("image.png", "rb") as f: + image_data = base64.standard_b64encode(f.read()).decode("utf-8") + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": image_data + } + }, + {"type": "text", "text": "What's in this image?"} + ] + }] +) +``` + +### URL + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "url", + "url": "https://example.com/image.png" + } + }, + {"type": "text", "text": "Describe this image"} + ] + }] +) +``` + +--- + +## Prompt Caching + +Cache large context to reduce costs (up to 90% savings). **Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block + system="You are an expert on this large document...", + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral"} # default TTL is 5 minutes + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# With explicit TTL (time-to-live) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Verifying Cache Hits + +```python +print(response.usage.cache_creation_input_tokens) # tokens written to cache (~1.25x cost) +print(response.usage.cache_read_input_tokens) # tokens served from cache (~0.1x cost) +print(response.usage.input_tokens) # uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `datetime.now()` or a UUID in the system prompt, unsorted `json.dumps()`, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```python +# Opus 4.6: adaptive thinking (recommended) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + thinking={"type": "adaptive"}, + output_config={"effort": "high"}, # low | medium | high | max + messages=[{"role": "user", "content": "Solve this step by step..."}] +) + +# Access thinking and response +for block in response.content: + if block.type == "thinking": + print(f"Thinking: {block.thinking}") + elif block.type == "text": + print(f"Response: {block.text}") +``` + +--- + +## Error Handling + +```python +import anthropic + +try: + response = client.messages.create(...) +except anthropic.BadRequestError as e: + print(f"Bad request: {e.message}") +except anthropic.AuthenticationError: + print("Invalid API key") +except anthropic.PermissionDeniedError: + print("API key lacks required permissions") +except anthropic.NotFoundError: + print("Invalid model or endpoint") +except anthropic.RateLimitError as e: + retry_after = int(e.response.headers.get("retry-after", "60")) + print(f"Rate limited. Retry after {retry_after}s.") +except anthropic.APIStatusError as e: + if e.status_code >= 500: + print(f"Server error ({e.status_code}). Retry later.") + else: + print(f"API error: {e.message}") +except anthropic.APIConnectionError: + print("Network error. Check internet connection.") +``` + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. + +```python +class ConversationManager: + """Manage multi-turn conversations with the Claude API.""" + + def __init__(self, client: anthropic.Anthropic, model: str, system: str = None): + self.client = client + self.model = model + self.system = system + self.messages = [] + + def send(self, user_message: str, **kwargs) -> str: + """Send a message and get a response.""" + self.messages.append({"role": "user", "content": user_message}) + + response = self.client.messages.create( + model=self.model, + max_tokens=kwargs.get("max_tokens", 16000), + system=self.system, + messages=self.messages, + **kwargs + ) + + assistant_message = next( + (b.text for b in response.content if b.type == "text"), "" + ) + self.messages.append({"role": "assistant", "content": assistant_message}) + + return assistant_message + +# Usage +conversation = ConversationManager( + client=anthropic.Anthropic(), + model="claude-opus-4-6", + system="You are a helpful assistant." +) + +response1 = conversation.send("My name is Alice.") +response2 = conversation.send("What's my name?") # Claude remembers "Alice" +``` + +**Rules:** + +- Messages must alternate between `user` and `assistant` +- First message must be `user` + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```python +import anthropic + +client = anthropic.Anthropic() +messages = [] + +def chat(user_message: str) -> str: + messages.append({"role": "user", "content": user_message}) + + response = client.beta.messages.create( + betas=["compact-2026-01-12"], + model="claude-opus-4-6", + max_tokens=16000, + messages=messages, + context_management={ + "edits": [{"type": "compact_20260112"}] + } + ) + + # Append full content — compaction blocks must be preserved + messages.append({"role": "assistant", "content": response.content}) + + return next(block.text for block in response.content if block.type == "text") + +# Compaction triggers automatically when context grows large +print(chat("Help me build a Python web scraper")) +print(chat("Add support for JavaScript-rendered pages")) +print(chat("Now add rate limiting and error handling")) +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +|-------|---------| +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match your schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```python +# Automatic caching (simplest — caches the last cacheable block) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, + system=large_document_text, # e.g., 50KB of context + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# First request: full cost +# Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Choose the Right Model + +```python +# Default to Opus for most tasks +response = client.messages.create( + model="claude-opus-4-6", # $5.00/$25.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing"}] +) + +# Use Sonnet for high-volume production workloads +standard_response = client.messages.create( + model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize this document"}] +) + +# Use Haiku only for simple, speed-critical tasks +simple_response = client.messages.create( + model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens + max_tokens=256, + messages=[{"role": "user", "content": "Classify this as positive or negative"}] +) +``` + +### 3. Use Token Counting Before Requests + +```python +count_response = client.messages.count_tokens( + model="claude-opus-4-6", + messages=messages, + system=system +) + +estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens +print(f"Estimated input cost: ${estimated_input_cost:.4f}") +``` + +--- + +## Retry with Exponential Backoff + +> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides. + +```python +import time +import random +import anthropic + +def call_with_retry( + client: anthropic.Anthropic, + max_retries: int = 5, + base_delay: float = 1.0, + max_delay: float = 60.0, + **kwargs +): + """Call the API with exponential backoff retry.""" + last_exception = None + + for attempt in range(max_retries): + try: + return client.messages.create(**kwargs) + except anthropic.RateLimitError as e: + last_exception = e + except anthropic.APIStatusError as e: + if e.status_code >= 500: + last_exception = e + else: + raise # Client errors (4xx except 429) should not be retried + + delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) + print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s") + time.sleep(delay) + + raise last_exception +``` diff --git a/junie/versions/2206.4/skills/claude-api/python/claude-api/batches.md b/junie/versions/2206.4/skills/claude-api/python/claude-api/batches.md new file mode 100644 index 0000000..bed5401 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/claude-api/batches.md @@ -0,0 +1,185 @@ +# Message Batches API — Python + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```python +import anthropic +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id="request-1", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize climate change impacts"}] + ) + ), + Request( + custom_id="request-2", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing basics"}] + ) + ), + ] +) + +print(f"Batch ID: {message_batch.id}") +print(f"Status: {message_batch.processing_status}") +``` + +--- + +## Poll for Completion + +```python +import time + +while True: + batch = client.messages.batches.retrieve(message_batch.id) + if batch.processing_status == "ended": + break + print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}") + time.sleep(60) + +print("Batch complete!") +print(f"Succeeded: {batch.request_counts.succeeded}") +print(f"Errored: {batch.request_counts.errored}") +``` + +--- + +## Retrieve Results + +> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead. + +```python +for result in client.messages.batches.results(message_batch.id): + match result.result.type: + case "succeeded": + msg = result.result.message + text = next((b.text for b in msg.content if b.type == "text"), "") + print(f"[{result.custom_id}] {text[:100]}") + case "errored": + if result.result.error.type == "invalid_request": + print(f"[{result.custom_id}] Validation error - fix request and retry") + else: + print(f"[{result.custom_id}] Server error - safe to retry") + case "canceled": + print(f"[{result.custom_id}] Canceled") + case "expired": + print(f"[{result.custom_id}] Expired - resubmit") +``` + +--- + +## Cancel a Batch + +```python +cancelled = client.messages.batches.cancel(message_batch.id) +print(f"Status: {cancelled.processing_status}") # "canceling" +``` + +--- + +## Batch with Prompt Caching + +```python +shared_system = [ + {"type": "text", "text": "You are a literary analyst."}, + { + "type": "text", + "text": large_document_text, # Shared across all requests + "cache_control": {"type": "ephemeral"} + } +] + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id=f"analysis-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + system=shared_system, + messages=[{"role": "user", "content": question}] + ) + ) + for i, question in enumerate(questions) + ] +) +``` + +--- + +## Full End-to-End Example + +```python +import anthropic +import time +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +# 1. Prepare requests +items_to_classify = [ + "The product quality is excellent!", + "Terrible customer service, never again.", + "It's okay, nothing special.", +] + +requests = [ + Request( + custom_id=f"classify-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-haiku-4-5", + max_tokens=50, + messages=[{ + "role": "user", + "content": f"Classify as positive/negative/neutral (one word): {text}" + }] + ) + ) + for i, text in enumerate(items_to_classify) +] + +# 2. Create batch +batch = client.messages.batches.create(requests=requests) +print(f"Created batch: {batch.id}") + +# 3. Wait for completion +while True: + batch = client.messages.batches.retrieve(batch.id) + if batch.processing_status == "ended": + break + time.sleep(10) + +# 4. Collect results +results = {} +for result in client.messages.batches.results(batch.id): + if result.result.type == "succeeded": + msg = result.result.message + results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "") + +for custom_id, classification in sorted(results.items()): + print(f"{custom_id}: {classification}") +``` diff --git a/junie/versions/2206.4/skills/claude-api/python/claude-api/files-api.md b/junie/versions/2206.4/skills/claude-api/python/claude-api/files-api.md new file mode 100644 index 0000000..93efef7 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/claude-api/files-api.md @@ -0,0 +1,165 @@ +# Files API — Python + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```python +import anthropic + +client = anthropic.Anthropic() + +uploaded = client.beta.files.upload( + file=("report.pdf", open("report.pdf", "rb"), "application/pdf"), +) +print(f"File ID: {uploaded.id}") +print(f"Size: {uploaded.size_bytes} bytes") +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```python +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Summarize the key findings in this report."}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id}, + "title": "Q4 Report", # optional + "citations": {"enabled": True} # optional, enables citations + } + ] + }], + betas=["files-api-2025-04-14"], +) +for block in response.content: + if block.type == "text": + print(block.text) +``` + +### Image + +```python +image_file = client.beta.files.upload( + file=("photo.png", open("photo.png", "rb"), "image/png"), +) + +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "What's in this image?"}, + { + "type": "image", + "source": {"type": "file", "file_id": image_file.id} + } + ] + }], + betas=["files-api-2025-04-14"], +) +``` + +--- + +## Manage Files + +### List Files + +```python +files = client.beta.files.list() +for f in files.data: + print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)") +``` + +### Get File Metadata + +```python +file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") +print(f"Filename: {file_info.filename}") +print(f"MIME type: {file_info.mime_type}") +``` + +### Delete a File + +```python +client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") +``` + +### Download a File + +Only files created by the code execution tool or skills can be downloaded (not user-uploaded files). + +```python +file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") +file_content.write_to_file("output.txt") +``` + +--- + +## Full End-to-End Example + +Upload a document once, ask multiple questions about it: + +```python +import anthropic + +client = anthropic.Anthropic() + +# 1. Upload once +uploaded = client.beta.files.upload( + file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"), +) +print(f"Uploaded: {uploaded.id}") + +# 2. Ask multiple questions using the same file_id +questions = [ + "What are the key terms and conditions?", + "What is the termination clause?", + "Summarize the payment schedule.", +] + +for question in questions: + response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": question}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id} + } + ] + }], + betas=["files-api-2025-04-14"], + ) + print(f"\nQ: {question}") + text = next((b.text for b in response.content if b.type == "text"), "") + print(f"A: {text[:200]}") + +# 3. Clean up when done +client.beta.files.delete(uploaded.id) +``` diff --git a/junie/versions/2206.4/skills/claude-api/python/claude-api/streaming.md b/junie/versions/2206.4/skills/claude-api/python/claude-api/streaming.md new file mode 100644 index 0000000..b21f9ae --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/claude-api/streaming.md @@ -0,0 +1,162 @@ +# Streaming — Python + +## Quick Start + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +### Async + +```python +async with async_client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + async for text in stream.text_stream: + print(text, end="", flush=True) +``` + +--- + +## Handling Different Content Types + +Claude may return text, thinking blocks, or tool use. Handle each appropriately: + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + thinking={"type": "adaptive"}, + messages=[{"role": "user", "content": "Analyze this problem"}] +) as stream: + for event in stream: + if event.type == "content_block_start": + if event.content_block.type == "thinking": + print("\n[Thinking...]") + elif event.content_block.type == "text": + print("\n[Response:]") + + elif event.type == "content_block_delta": + if event.delta.type == "thinking_delta": + print(event.delta.thinking, end="", flush=True) + elif event.delta.type == "text_delta": + print(event.delta.text, end="", flush=True) +``` + +--- + +## Streaming with Tool Use + +The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools: + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + tools=tools, + messages=messages +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + response = stream.get_final_message() + # Continue with tool execution if response.stop_reason == "tool_use" +``` + +--- + +## Getting the Final Message + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Hello"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + # Get full message after streaming + final_message = stream.get_final_message() + print(f"\n\nTokens used: {final_message.usage.output_tokens}") +``` + +--- + +## Streaming with Progress Updates + +```python +def stream_with_progress(client, **kwargs): + """Stream a response with progress updates.""" + total_tokens = 0 + content_parts = [] + + with client.messages.stream(**kwargs) as stream: + for event in stream: + if event.type == "content_block_delta": + if event.delta.type == "text_delta": + text = event.delta.text + content_parts.append(text) + print(text, end="", flush=True) + + elif event.type == "message_delta": + if event.usage and event.usage.output_tokens is not None: + total_tokens = event.usage.output_tokens + + final_message = stream.get_final_message() + + print(f"\n\n[Tokens used: {total_tokens}]") + return "".join(content_parts) +``` + +--- + +## Error Handling in Streams + +```python +try: + with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] + ) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +except anthropic.APIConnectionError: + print("\nConnection lost. Please retry.") +except anthropic.RateLimitError: + print("\nRate limited. Please wait and retry.") +except anthropic.APIStatusError as e: + print(f"\nAPI error: {e.status_code}") +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `flush=True` to show tokens immediately +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use timeouts** — Set appropriate timeouts for your application +5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events diff --git a/junie/versions/2206.4/skills/claude-api/python/claude-api/tool-use.md b/junie/versions/2206.4/skills/claude-api/python/claude-api/tool-use.md new file mode 100644 index 0000000..52bbe49 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/claude-api/tool-use.md @@ -0,0 +1,590 @@ +# Tool Use — Python + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the Python SDK. + +Use the `@beta_tool` decorator to define tools as typed functions, then pass them to `client.beta.messages.tool_runner()`: + +```python +import anthropic +from anthropic import beta_tool + +client = anthropic.Anthropic() + +@beta_tool +def get_weather(location: str, unit: str = "celsius") -> str: + """Get current weather for a location. + + Args: + location: City and state, e.g., San Francisco, CA. + unit: Temperature unit, either "celsius" or "fahrenheit". + """ + # Your implementation here + return f"72°F and sunny in {location}" + +# The tool runner handles the agentic loop automatically +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[get_weather], + messages=[{"role": "user", "content": "What's the weather in Paris?"}], +) + +# Each iteration yields a BetaMessage; iteration stops when Claude is done +for message in runner: + print(message) +``` + +For async usage, use `@beta_async_tool` with `async def` functions. + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via decorators +- Tool schemas are generated automatically from function signatures +- Iteration stops automatically when Claude has no more tool calls + +--- + +## MCP Tool Conversion Helpers + +**Beta.** Convert [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires `pip install anthropic[mcp]` (Python 3.10+). + +> **Note:** The Claude API also supports an `mcp_servers` parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection. + +### MCP Tools with Tool Runner + +```python +from anthropic import AsyncAnthropic +from anthropic.lib.tools.mcp import async_mcp_tool +from mcp import ClientSession +from mcp.client.stdio import stdio_client, StdioServerParameters + +client = AsyncAnthropic() + +async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write): + async with ClientSession(read, write) as mcp_client: + await mcp_client.initialize() + + tools_result = await mcp_client.list_tools() + # tool_runner is sync — returns the runner, not a coroutine + runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Use the available tools"}], + tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools], + ) + async for message in runner: + print(message) +``` + +For sync usage, use `mcp_tool` instead of `async_mcp_tool`. + +### MCP Prompts + +```python +from anthropic.lib.tools.mcp import mcp_message + +prompt = await mcp_client.get_prompt(name="my-prompt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[mcp_message(m) for m in prompt.messages], +) +``` + +### MCP Resources as Content + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_content + +resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + mcp_resource_to_content(resource), + {"type": "text", "text": "Summarize this document"}, + ], + }], +) +``` + +### Upload MCP Resources as Files + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_file + +resource = await mcp_client.read_resource(uri="file:///path/to/data.json") +uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource)) +``` + +Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types). + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval): + +```python +import anthropic + +client = anthropic.Anthropic() +tools = [...] # Your tool definitions +messages = [{"role": "user", "content": user_input}] + +# Agentic loop: keep going until Claude stops calling tools +while True: + response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=messages + ) + + # If Claude is done (no more tool calls), break + if response.stop_reason == "end_turn": + break + + # Server-side tool hit iteration limit; re-send to continue + if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_input}, + {"role": "assistant", "content": response.content}, + ] + continue + + # Extract tool use blocks from the response + tool_use_blocks = [b for b in response.content if b.type == "tool_use"] + + # Append assistant's response (including tool_use blocks) + messages.append({"role": "assistant", "content": response.content}) + + # Execute each tool and collect results + tool_results = [] + for tool in tool_use_blocks: + result = execute_tool(tool.name, tool.input) # Your implementation + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool.id, # Must match the tool_use block's id + "content": result + }) + + # Append tool results as a user message + messages.append({"role": "user", "content": tool_results}) + +# Final response text +final_text = next(b.text for b in response.content if b.type == "text") +``` + +--- + +## Handling Tool Results + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) + +for block in response.content: + if block.type == "tool_use": + tool_name = block.name + tool_input = block.input + tool_use_id = block.id + + result = execute_tool(tool_name, tool_input) + + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + {"role": "user", "content": "What's the weather in Paris?"}, + {"role": "assistant", "content": response.content}, + { + "role": "user", + "content": [{ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": result + }] + } + ] + ) +``` + +--- + +## Multiple Tool Calls + +```python +tool_results = [] + +for block in response.content: + if block.type == "tool_use": + result = execute_tool(block.name, block.input) + tool_results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": result + }) + +# Send all results back at once +if tool_results: + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + *previous_messages, + {"role": "assistant", "content": response.content}, + {"role": "user", "content": tool_results} + ] + ) +``` + +--- + +## Error Handling in Tool Results + +```python +tool_result = { + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": "Error: Location 'xyz' not found. Please provide a valid city name.", + "is_error": True +} +``` + +--- + +## Tool Choice + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) +``` + +--- + +## Code Execution + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" + }], + tools=[{ + "type": "code_execution_20260120", + "name": "code_execution" + }] +) + +for block in response.content: + if block.type == "text": + print(block.text) + elif block.type == "bash_code_execution_tool_result": + print(f"stdout: {block.content.stdout}") +``` + +### Upload Files for Analysis + +```python +# 1. Upload a file +uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb")) + +# 2. Pass to code execution via container_upload block +# Code execution is GA; Files API is still beta (pass via extra_headers) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + extra_headers={"anthropic-beta": "files-api-2025-04-14"}, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."}, + {"type": "container_upload", "file_id": uploaded.id} + ] + }], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Retrieve Generated Files + +```python +import os + +OUTPUT_DIR = "./claude_outputs" +os.makedirs(OUTPUT_DIR, exist_ok=True) + +for block in response.content: + if block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result" and result.content: + for file_ref in result.content: + if file_ref.type == "bash_code_execution_output": + metadata = client.beta.files.retrieve_metadata(file_ref.file_id) + file_content = client.beta.files.download(file_ref.file_id) + # Use basename to prevent path traversal; validate result + safe_name = os.path.basename(metadata.filename) + if not safe_name or safe_name in (".", ".."): + print(f"Skipping invalid filename: {metadata.filename}") + continue + output_path = os.path.join(OUTPUT_DIR, safe_name) + file_content.write_to_file(output_path) + print(f"Saved: {output_path}") +``` + +### Container Reuse + +```python +# First request: set up environment +response1 = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) + +# Get container ID from response +container_id = response1.container.id + +# Second request: reuse the same container +response2 = client.messages.create( + container=container_id, + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Response Structure + +```python +for block in response.content: + if block.type == "text": + print(block.text) # Claude's explanation + elif block.type == "server_tool_use": + print(f"Running: {block.name} - {block.input}") # What Claude is doing + elif block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result": + if result.return_code == 0: + print(f"Output: {result.stdout}") + else: + print(f"Error: {result.stderr}") + else: + print(f"Tool error: {result.error_code}") + elif block.type == "text_editor_code_execution_tool_result": + print(f"File operation: {block.content}") +``` + +--- + +## Memory Tool + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Remember that my preferred language is Python."}], + tools=[{"type": "memory_20250818", "name": "memory"}], +) +``` + +### SDK Memory Helper + +Subclass `BetaAbstractMemoryTool`: + +```python +from anthropic.lib.tools import BetaAbstractMemoryTool + +class MyMemoryTool(BetaAbstractMemoryTool): + def view(self, command): ... + def create(self, command): ... + def str_replace(self, command): ... + def insert(self, command): ... + def delete(self, command): ... + def rename(self, command): ... + +memory = MyMemoryTool() + +# Use with tool runner +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[memory], + messages=[{"role": "user", "content": "Remember my preferences"}], +) + +for message in runner: + print(message) +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py` + +--- + +## Structured Outputs + +### JSON Outputs (Pydantic — Recommended) + +```python +from pydantic import BaseModel +from typing import List +import anthropic + +class ContactInfo(BaseModel): + name: str + email: str + plan: str + interests: List[str] + demo_requested: bool + +client = anthropic.Anthropic() + +response = client.messages.parse( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo." + }], + output_format=ContactInfo, +) + +# response.parsed_output is a validated ContactInfo instance +contact = response.parsed_output +print(contact.name) # "Jane Doe" +print(contact.interests) # ["API", "SDKs"] +``` + +### Raw Schema + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract info: John Smith (john@example.com) wants the Enterprise plan." + }], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "email": {"type": "string"}, + "plan": {"type": "string"}, + "demo_requested": {"type": "boolean"} + }, + "required": ["name", "email", "plan", "demo_requested"], + "additionalProperties": False + } + } + } +) + +import json +# output_config.format guarantees the first block is text with valid JSON +text = next(b.text for b in response.content if b.type == "text") +data = json.loads(text) +``` + +### Strict Tool Use + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}], + tools=[{ + "name": "book_flight", + "description": "Book a flight to a destination", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"}, + "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]} + }, + "required": ["destination", "date", "passengers"], + "additionalProperties": False + } + }] +) +``` + +### Using Both Together + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Plan a trip to Paris next month"}], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "summary": {"type": "string"}, + "next_steps": {"type": "array", "items": {"type": "string"}} + }, + "required": ["summary", "next_steps"], + "additionalProperties": False + } + } + }, + tools=[{ + "name": "search_flights", + "description": "Search for available flights", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"} + }, + "required": ["destination", "date"], + "additionalProperties": False + } + }] +) +``` diff --git a/junie/versions/2206.4/skills/claude-api/python/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/python/managed-agents/README.md new file mode 100644 index 0000000..49b6783 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/python/managed-agents/README.md @@ -0,0 +1,329 @@ +# Managed Agents — Python + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") +``` + +--- + +## Create an Environment + +```python +environment = client.beta.environments.create( + name="my-dev-env", + config={ + "type": "cloud", + "networking": {"type": "unrestricted"}, + }, +) +print(environment.id) # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent={"type": "agent", "id": agent.id}`. + +### Minimal + +```python +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name="Coding Assistant", + model="claude-opus-4-6", + tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}], +) + +# 2. Start a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, +) +print(session.id, session.status) +``` + +### With system prompt and custom tools + +```python +import os + +agent = client.beta.agents.create( + name="Code Reviewer", + model="claude-opus-4-6", + system="You are a senior code reviewer.", + tools=[ + {"type": "agent_toolset_20260401"}, + { + "type": "custom", + "name": "run_tests", + "description": "Run the test suite", + "input_schema": { + "type": "object", + "properties": { + "test_path": {"type": "string", "description": "Path to test file"} + }, + "required": ["test_path"], + }, + }, + ], +) + +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + title="Code review session", + resources=[ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], + "branch": "main", + } + ], +) +``` + +--- + +## Send a User Message + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.message", + "content": [{"type": "text", "text": "Review the auth module"}], + } + ], +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```python +import json + +# Stream-first: open stream, then send while stream is live +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + client.beta.sessions.events.send( + session_id=session.id, + events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}], + ) + for event in stream: + ... # process events + +# Standalone stream iteration: +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + # Custom tool invocation — session is now idle + print(f"\nCustom tool call: {event.tool_name}") + print(f"Input: {json.dumps(event.input)}") + # Send result back (see below) + elif event.type == "session.status_idle": + print("\n--- Agent idle ---") + elif event.type == "session.status_terminated": + print("\n--- Session terminated ---") + break +``` + +--- + +## Provide Custom Tool Result + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{"type": "text", "text": "All 42 tests passed."}], + } + ], +) +``` + +--- + +## Poll Events + +```python +events = client.beta.sessions.events.list( + session_id=session.id, +) +for event in events.data: + print(f"{event.type}: {event.id}") +``` + +> ⚠️ **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration — both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events). + +--- + +## Full Streaming Loop with Custom Tools + +```python +import json + + +def run_custom_tool(tool_name: str, tool_input: dict) -> str: + """Execute a custom tool and return the result.""" + if tool_name == "run_tests": + # Your tool implementation here + return "All tests passed." + return f"Unknown tool: {tool_name}" + + +def run_session(client, session_id: str): + """Stream events and handle custom tool calls.""" + while True: + with client.beta.sessions.stream( + session_id=session_id, + ) as stream: + tool_calls = [] + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + tool_calls.append(event) + elif event.type == "session.status_idle": + break + elif event.type == "session.status_terminated": + return + + if not tool_calls: + break + + # Process custom tool calls + results = [] + for call in tool_calls: + result = run_custom_tool(call.tool_name, call.input) + results.append({ + "type": "user.custom_tool_result", + "custom_tool_use_id": call.id, + "content": [{"type": "text", "text": result}], + }) + + client.beta.sessions.events.send( + session_id=session_id, + events=results, + ) +``` + +--- + +## Upload a File + +```python +with open("data.csv", "rb") as f: + file = client.beta.files.upload( + file=f, + ) + +# Use in a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}], +) +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```python +# List files associated with a session +files = client.beta.files.list(session_id=session.id) +for f in files.data: + print(f.filename, f.size_bytes) + # Download each file and save to disk + file_content = client.beta.files.download(f.id) + file_content.write_to_file(f.filename) +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list` (with `scope=session_id` as a query param). Retry once or twice if the list is empty. + +--- + +## Session Management + +```python +# Get session details +session = client.beta.sessions.retrieve(session_id="sess_abc123") +print(session.status, session.usage) + +# List sessions +sessions = client.beta.sessions.list() + +# Delete a session +client.beta.sessions.delete(session_id="sess_abc123") + +# Archive a session +client.beta.sessions.archive(session_id="sess_abc123") +``` + +--- + +## MCP Server Integration + +```python +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name="MCP Agent", + model="claude-opus-4-6", + mcp_servers=[ + {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"}, + ], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "my-tools"}, + ], +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment.id, + vault_ids=[vault.id], +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2206.4/skills/claude-api/ruby/claude-api.md b/junie/versions/2206.4/skills/claude-api/ruby/claude-api.md new file mode 100644 index 0000000..21f5b12 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/ruby/claude-api.md @@ -0,0 +1,113 @@ +# Claude API — Ruby + +> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +--- + +## Basic Message Request + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "What is the capital of France?" } + ] +) +# content is an array of polymorphic block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text". +# .text raises NoMethodError on non-TextBlock entries. +message.content.each do |block| + puts block.text if block.type == :text +end +``` + +--- + +## Streaming + +```ruby +stream = client.messages.stream( + model: :"claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a haiku" }] +) + +stream.text.each { |text| print(text) } +``` + +--- + +## Tool Use + +The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution. + +### Tool Runner (Beta) + +```ruby +class GetWeatherInput < Anthropic::BaseModel + required :location, String, doc: "City and state, e.g. San Francisco, CA" +end + +class GetWeather < Anthropic::BaseTool + doc "Get the current weather for a location" + + input_schema GetWeatherInput + + def call(input) + "The weather in #{input.location} is sunny and 72°F." + end +end + +client.beta.messages.tool_runner( + model: :"claude-opus-4-6", + max_tokens: 16000, + tools: [GetWeather.new], + messages: [{ role: "user", content: "What's the weather in San Francisco?" }] +).each_message do |message| + puts message.content +end +``` + +### Manual Loop + +See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. + +--- + +## Prompt Caching + +`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + system_: [ + { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } } + ], + messages: [{ role: "user", content: "Summarize the key points" }] +) +``` + +For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block. + +Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`. diff --git a/junie/versions/2206.4/skills/claude-api/ruby/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/ruby/managed-agents/README.md new file mode 100644 index 0000000..e6bf24f --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/ruby/managed-agents/README.md @@ -0,0 +1,389 @@ +# Managed Agents — Ruby + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +> ⚠️ **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code. + +--- + +## Create an Environment + +```ruby +environment = client.beta.environments.create( + name: "my-dev-env", + config: { + type: "cloud", + networking: {type: "unrestricted"} + } +) +puts "Environment ID: #{environment.id}" # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` — the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`. + +### Minimal + +```ruby +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name: "Coding Assistant", + model: :"claude-opus-4-6", + system_: "You are a helpful coding assistant.", + tools: [{type: "agent_toolset_20260401"}] +) + +# 2. Start a session +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + title: "Quickstart session" +) +puts "Session ID: #{session.id}" +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```ruby +updated_agent = client.beta.agents.update( + agent.id, + version: agent.version, + system_: "You are a helpful coding agent. Always write tests." +) +puts "New version: #{updated_agent.version}" + +# List all versions +client.beta.agents.versions.list(agent.id).auto_paging_each do |version| + puts "Version #{version.version}: #{version.updated_at.iso8601}" +end + +# Archive the agent +archived = client.beta.agents.archive(agent.id) +puts "Archived at: #{archived.archived_at.iso8601}" +``` + +--- + +## Send a User Message + +```ruby +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Review the auth module"}] + }] +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```ruby +# Open the stream first, then send the user message +stream = client.beta.sessions.events.stream_events(session.id) + +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Summarize the repo README"}] + }] +) + +stream.each do |event| + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"agent.tool_use" + puts "\n[Using tool: #{event.name}]" + in :"session.status_idle" + break + in :"session.error" + puts "\n[Error: #{event.error&.message || "unknown"}]" + break + else + # ignore other event types + end +end +``` + +> ℹ️ Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`). + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```ruby +require "set" + +stream = client.beta.sessions.events.stream_events(session.id) + +# Stream is open and buffering. List history before tailing live. +seen_event_ids = Set.new +client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id } + +# Tail live events, skipping anything already seen +stream.each do |event| + next if seen_event_ids.include?(event.id) + seen_event_ids << event.id + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"session.status_idle" + break + else + # ignore other event types + end +end +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params. + +--- + +## Poll Events + +```ruby +client.beta.sessions.events.list(session.id).auto_paging_each do |event| + puts "#{event.type}: #{event.id}" +end +``` + +--- + +## Upload a File + +```ruby +require "pathname" + +file = client.beta.files.upload(file: Pathname("data.csv")) +puts "File ID: #{file.id}" + +# Mount in a session +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + resources: [ + { + type: "file", + file_id: file.id, + mount_path: "/workspace/data.csv" + } + ] +) +``` + +### Add and Manage Resources on an Existing Session + +```ruby +# Attach an additional file to an open session +resource = client.beta.sessions.resources.add( + session.id, + type: "file", + file_id: file.id +) +puts resource.id # "sesrsc_01ABC..." + +# List resources on the session +listed = client.beta.sessions.resources.list(session.id) +listed.data.each { |entry| puts "#{entry.id} #{entry.type}" } + +# Detach a resource +client.beta.sessions.resources.delete(resource.id, session_id: session.id) +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Ruby in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic` Ruby gem repository for the file list/download bindings. + +--- + +## Session Management + +```ruby +# List environments +environments = client.beta.environments.list + +# Retrieve a specific environment +env = client.beta.environments.retrieve(environment.id) + +# Archive an environment (read-only, existing sessions continue) +client.beta.environments.archive(environment.id) + +# Delete an environment (only if no sessions reference it) +client.beta.environments.delete(environment.id) + +# Delete a session +client.beta.sessions.delete(session.id) +``` + +--- + +## MCP Server Integration + +```ruby +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name: "GitHub Assistant", + model: :"claude-opus-4-6", + mcp_servers: [ + { + type: "url", + name: "github", + url: "https://api.githubcopilot.com/mcp/" + } + ], + tools: [ + {type: "agent_toolset_20260401"}, + {type: "mcp_toolset", mcp_server_name: "github"} + ] +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + vault_ids: [vault.id] +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```ruby +# Create a vault +vault = client.beta.vaults.create( + display_name: "Alice", + metadata: {external_user_id: "usr_abc123"} +) +puts vault.id # "vlt_01ABC..." + +# Add an OAuth credential +credential = client.beta.vaults.credentials.create( + vault.id, + display_name: "Alice's Slack", + auth: { + type: "mcp_oauth", + mcp_server_url: "https://mcp.slack.com/mcp", + access_token: "xoxp-...", + expires_at: "2026-04-15T00:00:00Z", + refresh: { + token_endpoint: "https://slack.com/api/oauth.v2.access", + client_id: "1234567890.0987654321", + scope: "channels:read chat:write", + refresh_token: "xoxe-1-...", + token_endpoint_auth: { + type: "client_secret_post", + client_secret: "abc123..." + } + } + } +) + +# Rotate the credential (e.g., after a token refresh) +client.beta.vaults.credentials.update( + credential.id, + vault_id: vault.id, + auth: { + type: "mcp_oauth", + access_token: "xoxp-new-...", + expires_at: "2026-05-15T00:00:00Z", + refresh: {refresh_token: "xoxe-1-new-..."} + } +) + +# Archive a vault +client.beta.vaults.archive(vault.id) +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```ruby +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], + resources: [ + { + type: "github_repository", + url: "https://github.com/org/repo", + mount_path: "/workspace/repo", + authorization_token: "ghp_your_github_token" + } + ] +) +``` + +Multiple repositories on the same session: + +```ruby +resources = [ + { + type: "github_repository", + url: "https://github.com/org/frontend", + mount_path: "/workspace/frontend", + authorization_token: "ghp_your_github_token" + }, + { + type: "github_repository", + url: "https://github.com/org/backend", + mount_path: "/workspace/backend", + authorization_token: "ghp_your_github_token" + } +] +``` + +Rotating a repository's authorization token: + +```ruby +listed = client.beta.sessions.resources.list(session.id) +repo_resource_id = listed.data.first.id + +client.beta.sessions.resources.update( + repo_resource_id, + session_id: session.id, + authorization_token: "ghp_your_new_github_token" +) +``` diff --git a/junie/versions/2206.4/skills/claude-api/shared/agent-design.md b/junie/versions/2206.4/skills/claude-api/shared/agent-design.md new file mode 100644 index 0000000..6756c39 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/agent-design.md @@ -0,0 +1,101 @@ +# Agent Design Patterns + +This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders. + +--- + +## Model Parameters + +| Parameter | When to use it | What to expect | +| --- | --- | --- | +| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. | +| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. | + +See `SKILL.md` §Thinking & Effort for model support and parameter details. + +--- + +## Designing Your Tool Surface + +### Bash vs. dedicated tools + +Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do. + +A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit. + +**When to promote an action to a dedicated tool:** + +- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not. +- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant. +- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered. +- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize. + +**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action. + +--- + +## Anthropic-Provided Tools + +| Tool | Side | When to use it | What to expect | +| --- | --- | --- | --- | +| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. | +| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. | +| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. | +| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. | +| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. | +| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. | + +**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest. + +--- + +## Composing Tool Calls: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again. + +**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude. + +| When to use it | What to expect | +| --- | --- | +| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. | + +--- + +## Scaling the Tool and Instruction Set + +| Feature | When to use it | What to expect | +| --- | --- | --- | +| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). | +| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. | + +Both patterns keep the fixed context small and load detail on demand. + +--- + +## Long-Running Agents: Managing Context + +| Pattern | When to use it | What to expect | +| --- | --- | --- | +| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. | +| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. | +| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. | + +**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three. + +--- + +## Caching for Agents + +**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints. + +| Constraint (from `prompt-caching.md`) | Agent-specific workaround | +| --- | --- | +| Editing the system prompt mid-session invalidates the cache. | Append a `` block in the `messages` array instead. The cached prefix stays intact. Claude Code uses this for time updates and mode transitions. | +| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. | +| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. | + +For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns. + +--- + +For live documentation on any of these features, see `live-sources.md`. diff --git a/junie/versions/2206.4/skills/claude-api/shared/error-codes.md b/junie/versions/2206.4/skills/claude-api/shared/error-codes.md new file mode 100644 index 0000000..9d08498 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/error-codes.md @@ -0,0 +1,206 @@ +# HTTP Error Codes Reference + +This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders. + +## Error Code Summary + +| Code | Error Type | Retryable | Common Cause | +| ---- | ----------------------- | --------- | ------------------------------------ | +| 400 | `invalid_request_error` | No | Invalid request format or parameters | +| 401 | `authentication_error` | No | Invalid or missing API key | +| 403 | `permission_error` | No | API key lacks permission | +| 404 | `not_found_error` | No | Invalid endpoint or model ID | +| 413 | `request_too_large` | No | Request exceeds size limits | +| 429 | `rate_limit_error` | Yes | Too many requests | +| 500 | `api_error` | Yes | Anthropic service issue | +| 529 | `overloaded_error` | Yes | API is temporarily overloaded | + +## Detailed Error Information + +### 400 Bad Request + +**Causes:** + +- Malformed JSON in request body +- Missing required parameters (`model`, `max_tokens`, `messages`) +- Invalid parameter types (e.g., string where integer expected) +- Empty messages array +- Messages not alternating user/assistant + +**Example error:** + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "messages: roles must alternate between \"user\" and \"assistant\"" + }, + "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" +} +``` + +**Fix:** Validate request structure before sending. Check that: + +- `model` is a valid model ID +- `max_tokens` is a positive integer +- `messages` array is non-empty and alternates correctly + +--- + +### 401 Unauthorized + +**Causes:** + +- Missing `x-api-key` header or `Authorization` header +- Invalid API key format +- Revoked or deleted API key + +**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly. + +--- + +### 403 Forbidden + +**Causes:** + +- API key doesn't have access to the requested model +- Organization-level restrictions +- Attempting to access beta features without beta access + +**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features. + +--- + +### 404 Not Found + +**Causes:** + +- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`) +- Using deprecated model ID +- Invalid API endpoint + +**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-6`). + +--- + +### 413 Request Too Large + +**Causes:** + +- Request body exceeds maximum size +- Too many tokens in input +- Image data too large + +**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks. + +--- + +### 400 Validation Errors + +Some 400 errors are specifically related to parameter validation: + +- `max_tokens` exceeds model's limit +- Invalid `temperature` value (must be 0.0-1.0) +- `budget_tokens` >= `max_tokens` in extended thinking +- Invalid tool definition schema + +**Common mistake with extended thinking:** + +``` +# Wrong: budget_tokens must be < max_tokens +thinking: budget_tokens=10000, max_tokens=1000 → Error! + +# Correct +thinking: budget_tokens=10000, max_tokens=16000 +``` + +--- + +### 429 Rate Limited + +**Causes:** + +- Exceeded requests per minute (RPM) +- Exceeded tokens per minute (TPM) +- Exceeded tokens per day (TPD) + +**Headers to check:** + +- `retry-after`: Seconds to wait before retrying +- `x-ratelimit-limit-*`: Your limits +- `x-ratelimit-remaining-*`: Remaining quota + +**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples. + +--- + +### 500 Internal Server Error + +**Causes:** + +- Temporary Anthropic service issue +- Bug in API processing + +**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com). + +--- + +### 529 Overloaded + +**Causes:** + +- High API demand +- Service capacity reached + +**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing. + +--- + +## Common Mistakes and Fixes + +| Mistake | Error | Fix | +| ------------------------------- | ---------------- | ------------------------------------------------------- | +| `budget_tokens` >= `max_tokens` | 400 | Ensure `budget_tokens` < `max_tokens` | +| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-6` | +| First message is `assistant` | 400 | First message must be `user` | +| Consecutive same-role messages | 400 | Alternate `user` and `assistant` | +| API key in code | 401 (leaked key) | Use environment variable | +| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` | + +## Typed Exceptions in SDKs + +**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class: + +| HTTP Code | TypeScript Class | Python Class | +| --------- | --------------------------------- | --------------------------------- | +| 400 | `Anthropic.BadRequestError` | `anthropic.BadRequestError` | +| 401 | `Anthropic.AuthenticationError` | `anthropic.AuthenticationError` | +| 403 | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` | +| 404 | `Anthropic.NotFoundError` | `anthropic.NotFoundError` | +| 429 | `Anthropic.RateLimitError` | `anthropic.RateLimitError` | +| 500+ | `Anthropic.InternalServerError` | `anthropic.InternalServerError` | +| Any | `Anthropic.APIError` | `anthropic.APIError` | + +```typescript +// ✅ Correct: use typed exceptions +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.RateLimitError) { + // Handle rate limiting + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} + +// ❌ Wrong: don't check error messages with string matching +try { + const response = await client.messages.create({...}); +} catch (error) { + const msg = error instanceof Error ? error.message : String(error); + if (msg.includes("429") || msg.includes("rate_limit")) { ... } +} +``` + +All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`). diff --git a/junie/versions/2206.4/skills/claude-api/shared/live-sources.md b/junie/versions/2206.4/skills/claude-api/shared/live-sources.md new file mode 100644 index 0000000..343e9d7 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/live-sources.md @@ -0,0 +1,131 @@ +# Live Documentation Sources + +This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated. + +## When to Use WebFetch + +- User explicitly asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered in cached content +- User needs specific API details or examples + +## Claude API Documentation URLs + +### Models & Pricing + +| Topic | URL | Extraction Prompt | +| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" | +| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" | + +### Core Features + +| Topic | URL | Extraction Prompt | +| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" | +| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.6 usage examples" | +| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" | +| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" | +| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" | +| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" | + +### Media & Files + +| Topic | URL | Extraction Prompt | +| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" | +| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" | + +### API Operations + +| Topic | URL | Extraction Prompt | +| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" | +| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" | +| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" | +| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" | +| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" | + +### Tools + +| Topic | URL | Extraction Prompt | +| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" | +| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" | +| Bash Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md` | "Extract bash tool schema, reference implementation, and security considerations" | +| Text Editor | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md` | "Extract text editor tool commands, schema, and reference implementation" | +| Memory Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` | "Extract memory tool commands, directory structure, and implementation patterns" | +| Tool Search | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md` | "Extract tool search setup, when to use, and cache interaction" | +| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code" | +| Skills | `https://platform.claude.com/docs/en/agents-and-tools/skills.md` | "Extract skill folder structure, SKILL.md format, and loading behavior" | + +### Advanced Features + +| Topic | URL | Extraction Prompt | +| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- | +| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" | +| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" | +| Context Editing | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md` | "Extract context editing thresholds, what gets cleared, and configuration" | +| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" | +| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" | + +### Managed Agents + +Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`. + +| Topic | URL | Extraction Prompt | +| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Overview | `https://platform.claude.com/docs/en/managed-agents/overview.md` | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" | +| Quickstart | `https://platform.claude.com/docs/en/managed-agents/quickstart.md` | "Extract the minimal end-to-end agent → environment → session → stream code path" | +| Agent Setup | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md` | "Extract agent create/update/list-versions/archive lifecycle and parameters" | +| Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" | +| Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" | +| Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" | +| Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" | +| Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" | +| Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" | +| Permission Policies | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md` | "Extract permission policy types (allow/deny/confirm) and per-tool config" | +| Multi-Agent | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff" | +| Observability | `https://platform.claude.com/docs/en/managed-agents/observability.md` | "Extract logging, tracing, and usage telemetry exposed by managed agents" | +| GitHub | `https://platform.claude.com/docs/en/managed-agents/github.md` | "Extract github_repository resource shape, multi-repo mounting, and token rotation" | +| MCP Connector | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md` | "Extract MCP server declaration on agents and vault-based credential injection at session" | +| Vaults | `https://platform.claude.com/docs/en/managed-agents/vaults.md` | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive" | +| Skills | `https://platform.claude.com/docs/en/managed-agents/skills.md` | "Extract skill packaging and loading model for managed agents" | +| Memory | `https://platform.claude.com/docs/en/managed-agents/memory.md` | "Extract memory resource shape, scoping, and lifecycle" | +| Onboarding | `https://platform.claude.com/docs/en/managed-agents/onboarding.md` | "Extract first-run setup, prerequisites, and account/region requirements" | +| Cloud Containers | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md` | "Extract cloud container runtime, image config, and network/storage knobs" | +| Migration | `https://platform.claude.com/docs/en/managed-agents/migration.md` | "Extract migration paths from earlier APIs/preview shapes to GA managed agents" | + +### Anthropic CLI + +The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively. + +| Topic | URL | Extraction Prompt | +| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md` | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" | + +--- + +## Claude API SDK Repositories + +WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language. + +| SDK | URL | Extraction Prompt | +| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| Python | `https://github.com/anthropics/anthropic-sdk-python` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| Java | `https://github.com/anthropics/anthropic-sdk-java` | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" | +| Go | `https://github.com/anthropics/anthropic-sdk-go` | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)" | +| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)" | +| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)" | +| PHP | `https://github.com/anthropics/anthropic-sdk-php` | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)" | + +--- + +## Fallback Strategy + +If WebFetch fails (network issues, URL changed): + +1. Use cached content from the language-specific files (note the cache date) +2. Inform user the data may be outdated +3. Suggest they check platform.claude.com or the GitHub repos directly diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-api-reference.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-api-reference.md new file mode 100644 index 0000000..155c877 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-api-reference.md @@ -0,0 +1,299 @@ +# Managed Agents — Endpoint Reference + +All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header. + +## Beta Headers + +``` +anthropic-beta: managed-agents-2026-04-01 +``` + +The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`. + +--- + +## SDK Method Reference + +All resources are under the `beta` namespace. Python and TypeScript share identical method names. + +| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) | +| --- | --- | --- | +| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` | +| Agent Versions | `agents.versions.list` | `Agents.Versions.List` | +| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` | +| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` | +| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | + +**Naming quirks to watch for:** +- Agents have **no delete** — only `archive`. Other resources have both. +- Session resources use `add` (not `create`). +- Go's event stream is `StreamEvents` (not `Stream`). + +**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`). + +**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-6"` — uses `standard` speed) or the full config object (`{type: "model_config", id: "claude-opus-4-6", speed: "fast"}`). + +--- + +## Agents + +**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/agents` | ListAgents | List agents | +| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration | +| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details | +| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration | +| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent (no hard delete for agents) | +| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions | + +## Sessions + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) | +| `POST` | `/v1/sessions` | CreateSession | Create a new session | +| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details | +| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title | +| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session | +| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session | + +## Events + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) | +| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) | +| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE | + +## Session Resources + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session | +| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach file or github_repository mount (SDK method: `add`, not `create`) | +| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource | +| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource | +| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session | + +## Environments + +| Method | Path | Operation | Description | +| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- | +| `POST` | `/v1/environments` | CreateEnvironment | Create environment | +| `GET` | `/v1/environments` | ListEnvironments | List environments | +| `GET` | `/v1/environments/{environment_id}` | GetEnvironment | Get environment details | +| `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment | +| `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. | +| `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment (read-only; existing sessions continue) | + +## Vaults + +Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/vaults` | CreateVault | Create a vault | +| `GET` | `/v1/vaults` | ListVaults | List vaults | +| `GET` | `/v1/vaults/{vault_id}` | GetVault | Get vault details | +| `POST` | `/v1/vaults/{vault_id}` | UpdateVault | Update vault | +| `DELETE` | `/v1/vaults/{vault_id}` | DeleteVault | Delete vault | +| `POST` | `/v1/vaults/{vault_id}/archive` | ArchiveVault | Archive vault | + +## Credentials + +Credentials are individual secrets stored inside a vault. + +| Method | Path | Operation | Description | +| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/vaults/{vault_id}/credentials` | CreateCredential | Create a credential | +| `GET` | `/v1/vaults/{vault_id}/credentials` | ListCredentials | List credentials in vault | +| `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | GetCredential | Get credential metadata | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | UpdateCredential | Update credential | +| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | DeleteCredential | Delete credential | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | ArchiveCredential | Archive credential | + +## Files + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/files` | UploadFile | Upload a file | +| `GET` | `/v1/files` | ListFiles | List files | +| `GET` | `/v1/files/{file_id}` | GetFile | Get file metadata (SDK method: `retrieve_metadata`) | +| `GET` | `/v1/files/{file_id}/content` | DownloadFile | Download file content | +| `DELETE` | `/v1/files/{file_id}` | DeleteFile | Delete a file | + +## Skills + +| Method | Path | Operation | Description | +| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/skills` | CreateSkill | Create a skill | +| `GET` | `/v1/skills` | ListSkills | List skills | +| `GET` | `/v1/skills/{skill_id}` | GetSkill | Get skill details | +| `DELETE` | `/v1/skills/{skill_id}` | DeleteSkill | Delete a skill | +| `POST` | `/v1/skills/{skill_id}/versions` | CreateVersion | Create skill version | +| `GET` | `/v1/skills/{skill_id}/versions` | ListVersions | List skill versions | +| `GET` | `/v1/skills/{skill_id}/versions/{version}` | GetVersion | Get skill version | +| `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | DeleteVersion | Delete skill version | + +--- + +## Request/Response Schema Quick Reference + +### CreateAgent Request Body + +**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session. + +```json +{ + "name": "string (required, 1-256 chars)", + "model": "claude-opus-4-6 (required — bare string, or {id, speed} object)", + "description": "string (optional, up to 2048 chars)", + "system": "string (optional, up to 100,000 chars)", + "tools": [ + { "type": "agent_toolset_20260401" } + ], + "skills": [ + { "type": "anthropic", "skill_id": "xlsx" }, + { "type": "custom", "skill_id": "skill_abc123", "version": "1" } + ], + "mcp_servers": [ + { + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/" + } + ], + "metadata": { + "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)" + } +} +``` + +> Limits: `tools` max 50, `skills` max 64, `mcp_servers` max 20 (unique names). + +### CreateSession Request Body + +```json +{ + "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)", + "environment_id": "env_abc123 (required)", + "title": "string (optional)", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo (required)", + "authorization_token": "ghp_... (required)", + "mount_path": "/workspace/repo (optional — defaults to /workspace/)", + "checkout": { "type": "branch", "name": "main" } + } + ], + "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"], + "metadata": { + "key": "value" + } +} +``` + +> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here. +> +> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch. + +### CreateEnvironment Request Body + +```json +{ + "name": "string (required)", + "description": "string (optional)", + "config": { + "type": "cloud", + "networking": { + "type": "unrestricted | limited (union — see SDK types)" + }, + "packages": { } + }, + "metadata": { "key": "value" } +} +``` + +### SendEvents Request Body + +```json +{ + "events": [ + { + "type": "user.message", + "content": [ + { + "type": "text", + "text": "Hello" + } + ] + } + ] +} +``` + +### Tool Result Event + +```json +{ + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "Result data" }], + "is_error": false +} +``` + +--- + +## Error Handling + +Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`: + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "Description of what went wrong" + }, + "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE" +} +``` + +Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following: + +| Status | Error type | Description | +|---|---|---| +| 400 | `invalid_request_error` | The request was malformed or missing required parameters | +| 401 | `authentication_error` | Invalid or missing API key | +| 403 | `permission_error` | The API key doesn't have permission for this operation | +| 404 | `not_found_error` | The requested resource doesn't exist | +| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) | +| 413 | `request_too_large` | The request body exceeds the maximum allowed size | +| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing | +| 500 | `api_error` | An internal server error occurred | +| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff | + +Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests. + +--- + +## Rate Limits + +Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits. + +| Endpoint group | Scope | RPM | Max concurrent | +|---|---|---|---| +| Create operations (Agents, Sessions, Vaults) | organization | 60 | — | +| All other operations (Agents, Sessions, Vaults) | organization | 600 | — | +| All operations (Environments) | organization | 60 | 5 | + +Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits). + +When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically. diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-client-patterns.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-client-patterns.md new file mode 100644 index 0000000..784a601 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-client-patterns.md @@ -0,0 +1,205 @@ +# Managed Agents — Common Client Patterns + +Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples. + +Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents. + +--- + +## 1. Lossless stream reconnect + +**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between. + +**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up. + +```ts +const seenEventIds = new Set() +const stream = await client.beta.sessions.events.stream(session.id) + +// Stream is now open and buffering server-side. Read history first. +for await (const event of client.beta.sessions.events.list(session.id)) { + seenEventIds.add(event.id) + handle(event) +} + +// Tail the live stream. Dedupe only gates handle() — terminal checks must run +// even for already-seen events, or a terminal event that was in the history +// response gets skipped by `continue` and the loop never exits. +for await (const event of stream) { + if (!seenEventIds.has(event.id)) { + seenEventIds.add(event.id) + handle(event) + } + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break +} +``` + +--- + +## 2. `processed_at` — queued vs processed + +Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp. + +```ts +for await (const event of stream) { + if (event.type === 'user.message') { + if (event.processed_at == null) onQueued(event.id) + else onProcessed(event.id, event.processed_at) + } +} +``` + +Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering). + +--- + +## 3. Interrupt a running session + +Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle. + +```ts +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.interrupt' }], +}) + +// Drain until the session is truly done — see Pattern 5 for the full gate. +for await (const event of stream) { + if (event.type === 'session.status_terminated') break + if ( + event.type === 'session.status_idle' && + event.stop_reason.type !== 'requires_action' + ) break +} +``` + +Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`. + +--- + +## 4. `tool_confirmation` round-trip + +When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`. + +```ts +for await (const event of stream) { + if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') { + await client.beta.sessions.events.send(session.id, { + events: [{ + type: 'user.tool_confirmation', + tool_use_id: event.id, // not a toolu_ id — use event.id + result: 'allow', // or 'deny' + // deny_message: '...', // optional, only with result: 'deny' + }], + }) + } +} +``` + +Key points: +- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID. +- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent. +- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`. + +Reference: `tool-permissions.ts`. + +--- + +## 5. Correct idle-break gate + +Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`. + +```ts +for await (const event of stream) { + handle(event) + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle') { + if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it + break // end_turn or retries_exhausted — both terminal + } +} +``` + +`stop_reason.type` values on `session.status_idle`: +- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break. +- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state. +- `end_turn` — normal completion. + +--- + +## 6. Post-idle status-write race + +The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running." + +Poll before cleanup: + +```ts +let s +for (let i = 0; i < 10; i++) { + s = await client.beta.sessions.retrieve(session.id) + if (s.status !== 'running') break + await new Promise(r => setTimeout(r, 200)) +} +if (s?.status !== 'running') { + await client.beta.sessions.archive(session.id) +} // else: still running after 2s — don't archive, let it settle or escalate +``` + +--- + +## 7. Stream-first, then send + +Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them. + +```ts +const stream = await client.beta.sessions.events.stream(session.id) +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }], +}) +for await (const event of stream) { /* ... */ } +``` + +The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened. + +--- + +## 8. File-mount gotchas + +**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy. + +```ts +const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' }) +// uploaded.id → the original file +const session = await client.beta.sessions.create({ + /* ... */ + resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }], +}) +// session.resources[0].file_id !== uploaded.id ← different IDs +``` + +Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`. + +--- + +## 9. Keep credentials host-side via custom tools + +**Problem:** putting a third-party API key in the agent's vault or environment means the sandbox holds the secret. For keys tied to a human (Linear personal keys, `gh` CLI auth) or keys you'd rather not ship into a container, that's undesirable. + +**Solution:** expose the operation as a custom tool. The agent emits `agent.custom_tool_use`; your orchestrator executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key. + +```ts +// Agent template: declare the tool, no credentials +tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }] + +// Orchestrator: handle the call with host-side creds +for await (const event of stream) { + if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') { + const result = await linear.request(event.input.query, event.input.vars) // host's key + await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }], + }) + } +} +``` + +Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-only auth or binaries. diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-core.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-core.md new file mode 100644 index 0000000..2eb1e47 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-core.md @@ -0,0 +1,216 @@ +# Managed Agents — Core Concepts + +## Architecture + +Managed Agents is built around four core concepts: + +| Concept | Endpoint | What it is | +|---|---|---| +| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. | +| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. | +| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. | +| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. | + +``` + ┌─────────────────────────────────────┐ + │ Anthropic orchestration layer │ +Agent (config) ───────▶│ (agent loop: Claude + tool calls) │ + └──────────────┬──────────────────────┘ + │ tool calls + ▼ +Environment (template) ──▶ Container (tool execution workspace) + │ + Session ─┤ + ├── Resources (files, repos — mounted at startup) + ├── Vault IDs (MCP credential references) + └── Conversation (event stream in/out) +``` + +> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`. + +--- + +## Session Lifecycle + +``` +rescheduling → running ↔ idle → terminated +``` + +| Status | Description | +| -------------- | ------------------------------------------------------------------ | +| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `running` | Session has starting running, and the Agent is actively doing work. | +| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `terminated` | Session has terminated, entering an irreversible and unusable state. | + +- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order. +- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done. +- Errors surface as `session.error` events in the stream, not as a status value. + +### Built-in session features + +- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going +- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost +- **Extended thinking** — on by default, returned as `agent.thinking` events + +### Session operations + +| Operation | Notes | +|---|---| +| List / fetch | Paginated list or single resource by ID | +| Update | Only `title` is updatable | +| Archive | Session becomes **read-only**. Not reversible. | +| Delete | Permanently deletes session, event history, container, and checkpoints. | + +--- + +## Sessions + +A session is a running agent instance inside an environment. + +### Session Object + +Key fields returned by the API: + +| Field | Type | Description | +| --------------- | -------- | --------------------------------------------------- | +| `type` | string | Always `"session"` | +| `id` | string | Unique session ID | +| `title` | string | Human-readable title | +| `status` | string | `idle`, `running`, `rescheduling`, `terminated` | +| `created_at` | string | ISO 8601 timestamp | +| `updated_at` | string | ISO 8601 timestamp | +| `archived_at` | string | ISO 8601 timestamp (nullable) | +| `environment_id` | string | Environment ID | +| `agent` | object | Agent configuration | +| `resources` | array | Attached files and repos | +| `metadata` | object | User-provided key-value pairs (max 8 keys) | +| `usage` | object | Token usage statistics | + +### Creating a session + +**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it: + +```ts +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + system: "You are a helpful coding agent.", + tools: [{ type: "agent_toolset_20260401"}], + }, +); + +// 2. Start a session that references it +const session = await client.beta.sessions.create( + { + agent: agent.id, // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version } + environment_id: environmentId, + title: "Hello World Session", + }, +); +``` + +**Session creation parameters:** + +| Field | Type | Required | Description | +| --------------- | -------- | -------- | ---------------------------------------------- | +| `agent` | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` | +| `environment_id`| string | **Yes** | Environment ID | +| `title` | string | No | Human-readable name (appears in logs/dashboards) | +| `resources` | array | No | Files or GitHub repos, mounted to the container at startup | +| `vault_ids` | array | No | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. | +| `metadata` | object | No | User-provided key-value pairs | + +**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`): + +| Field | Type | Required | Description | +| ------------- | -------- | -------- | ---------------------------------------------- | +| `name` | string | **Yes** | Human-readable name (1-256 chars) | +| `model` | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. | +| `system` | string | No | System prompt — defines the agent's behavior (up to 100K chars) | +| `tools` | array | No | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. | +| `mcp_servers` | array | No | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. | +| `skills` | array | No | Customized "best-practices" context with progressive disclosure. Max 64. See `shared/managed-agents-tools.md` → Skills. | +| `description` | string | No | Description of the agent (up to 2048 chars) | +| `metadata` | object | No | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) | + +--- + +## Agents + +**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session. + +### Agent Object + +The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object. + +| Field | Type | Required | Description | +| ------------------ | -------- | -------- | -------------------------------------------------- | +| `name` | string | Yes | Human-readable name | +| `model` | string | Yes | Claude model ID | +| `system` | string | No | System prompt | +| `tools` | array | No | Agent toolset / MCP toolset / custom tools | +| `mcp_servers` | array | No | MCP server connections | +| `skills` | array | No | Skill references (max 64) | +| `description` | string | No | Description of the agent | +| `metadata` | object | No | Arbitrary key-value pairs | + +### Lifecycle: create once, run many, update in place + +The agent is a **persistent resource**, not a per-run parameter. The intended pattern: + +``` +┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐ +│ agents.create() │ │ sessions.create( │ +│ → store agent_id │ ──→ │ agent={type:..., id: ID} │ +│ in config/env/db │ │ ) │ +└────────────────────────┘ └──────────────────────────────┘ +``` + +**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID. + +### Versioning + +Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version. + +**Why version:** +- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}` +- **Safe iteration** — update the agent without breaking sessions already running on the old version +- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug + +**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility. + +**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`. + +**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update. + +### Agent Endpoints + +| Operation | Method | Path | +| ---------------- | -------- | ------------------------------------- | +| Create | `POST` | `/v1/agents` | +| List | `GET` | `/v1/agents` | +| Get | `GET` | `/v1/agents/{id}` | +| Update | `POST` | `/v1/agents/{id}` | +| Archive | `POST` | `/v1/agents/{id}/archive` | + +### Using an Agent in a Session + +Reference the agent by string ID (latest version) or by object with an explicit version: + +```python +# String shorthand — uses the agent's latest version +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment_id, +) + +# Or pin to a specific version (int) +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment_id, +) +``` + diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-environments.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-environments.md new file mode 100644 index 0000000..64cfefd --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-environments.md @@ -0,0 +1,202 @@ +# Managed Agents — Environments & Resources + +## Environments + +Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration. + +**Environment names must be unique.** Creating an environment with an existing name returns 409. + +### Networking + +| Network Policy | Description | +| ------------------------------- | ------------------------------------------------------------- | +| `unrestricted` | Full egress (except legal blocklist) | +| `package_managers_and_custom` | Package managers + custom `allowed_hosts` | + +```json +{ + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } +} +``` + +**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail. + +### Creating an environment + +The SDK adds `managed-agents-2026-04-01` automatically. TypeScript: + +```ts +const env = await client.beta.environments.create({ + name: "my_env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, +}); +``` + +### Environment CRUD + +| Operation | Method | Path | Notes | +| ---------------- | -------- | ------------------------------------------ | ----- | +| Create | `POST` | `/v1/environments` | | +| List | `GET` | `/v1/environments` | Paginated (`limit`, `after_id`, `before_id`) | +| Get | `GET` | `/v1/environments/{id}` | | +| Update | `POST` | `/v1/environments/{id}` | Changes apply only to **new** containers; existing sessions keep their original config | +| Delete | `DELETE` | `/v1/environments/{id}` | Returns 204. | +| Archive | `POST` | `/v1/environments/{id}/archive` | Read-only. New sessions can't be created; existing ones continue. | + +--- + +## Resources + +Attach files and GitHub repositories to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. + +### File Uploads (input — host → agent) + +Upload a file first via the Files API, then reference by `file_id` + `mount_path`: + +```ts +// 1. Upload +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// 2. Attach as a session resource +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + resources: [ + { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" } + ], +}); +``` + +**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths. + +### Session outputs (output — agent → host) + +The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards: + +```ts +// After the turn completes, list output files scoped to this session: +for await (const f of client.beta.files.list({ scope: session.id })) { + console.log(f.filename, f.size_bytes); + const resp = await client.beta.files.download(f.id); + const text = await resp.text(); +} +``` + +**Requirements:** +- The `write` tool (or `bash`) must be enabled for the agent to create output files. +- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`. +- `session_id` is a query filter on `files.list` (not yet in SDK types — cast or spread through). +- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty. + +This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out. + +### GitHub Repositories + +Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. + +**Fields:** + +| Field | Required | Notes | +|---|---|---| +| `type` | ✅ | `"github_repository"` | +| `url` | ✅ | The GitHub repository URL | +| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** | +| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/`. | +| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. | + +**Token permission levels** (fine-grained PATs): +- `Contents: Read` — clone only +- `Contents: Read and write` — push changes and create pull requests + +> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` → create PR via MCP `create_pull_request` tool. + +**TypeScript:** + +```ts +// 1. Create the agent — declare GitHub MCP (no auth here) +const agent = await client.beta.agents.create( + { + name: 'GitHub Agent', + model: 'claude-opus-4-6', + mcp_servers: [ + { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' }, + ], + tools: [ + { type: 'agent_toolset_20260401', default_config: { enabled: true } }, + { type: 'mcp_toolset', mcp_server_name: 'github' }, + ], + }, +); + +// 2. Start a session — attach vault for MCP auth + mount the repo +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential + resources: [ + { + type: 'github_repository', + url: 'https://github.com/owner/repo', + authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth) + checkout: { type: 'branch', name: 'main' }, + }, + ], +}); +``` + +**Python:** + +```python +import os + +agent = client.beta.agents.create( + name="GitHub Agent", + model="claude-opus-4-6", + mcp_servers=[{ + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/", + }], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "github"}, + ], +) + +session = client.beta.sessions.create( + agent=agent.id, + environment_id=env_id, + vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential + resources=[{ + "type": "github_repository", + "url": "https://github.com/owner/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth) + "checkout": {"type": "branch", "name": "main"}, + }], +) +``` + +--- + +## Files API + +Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`. + +| Operation | Method | Path | SDK | +| ---------------- | -------- | ------------------------------------- | --- | +| Upload | `POST` | `/v1/files` | `client.beta.files.upload({ file })` | +| List | `GET` | `/v1/files?session_id=...` | `client.beta.files.list({ session_id })` | +| Get Metadata | `GET` | `/v1/files/{id}` | `client.beta.files.retrieveMetadata(id)` | +| Download | `GET` | `/v1/files/{id}/content` | `client.beta.files.download(id)` → `Response` | +| Delete | `DELETE` | `/v1/files/{id}` | `client.beta.files.delete(id)` | + +The `session_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account. diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-events.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-events.md new file mode 100644 index 0000000..5b10581 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-events.md @@ -0,0 +1,187 @@ +# Managed Agents — Events & Steering + +## Events + +### Sending Events + +Send events to a session via `POST /v1/sessions/{id}/events`. + +| Event Type | When to Send | +| ------------------------- | --------------------------------------------------- | +| `user.message` | Send a user message | +| `user.interrupt` | Interrupt the agent while it's running | +| `user.tool_confirmation` | Approve/deny a tool call (when `always_ask` policy) | +| `user.custom_tool_result` | Provide result for a custom tool call | + +### Receiving Events + +Two methods: + +1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive. +2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll. + +All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent). + +> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely. +> +> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem. + +### Event Types (Received) + +Event types use dot notation, grouped by namespace: + +| Event Type | Description | +| --- | --- | +| `agent.message` | Agent text output | +| `agent.thinking` | Extended thinking blocks | +| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) | +| `agent.tool_result` | Result from a built-in tool | +| `agent.mcp_tool_use` | Agent used an MCP tool | +| `agent.mcp_tool_result` | Result from an MCP tool | +| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` | +| `agent.thread_context_compacted` | Conversation context was compacted | +| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `session.status_running` | Session has starting running, and the Agent is actively doing work. | +| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state. | +| `session.error` | Error occurred during processing | +| `span.model_request_start` | Model inference started | +| `span.model_request_end` | Model inference completed | + +The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`). + +--- + +## Steering Patterns + +Practical patterns for driving a session via the events surface. + +### Stream-first ordering + +**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time. + +```ts +// ✅ Correct — stream and send concurrently +const [response] = await Promise.all([ + streamEvents(sessionId), // opens SSE connection + sendMessage(sessionId, text), +]); + +// ❌ Wrong — events before stream opens arrive as a single buffered batch +await sendMessage(sessionId, text); +const response = await streamEvents(sessionId); +``` + +**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward. + +### Reconnecting after a dropped stream + +**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream. + +**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID: + +```python +def connect_with_consolidation(client, session_id): + # 1. Open the SSE stream first + stream = client.beta.sessions.events.stream(session_id=session_id) + + # 2. Fetch history to cover any gap + history = client.beta.sessions.events.list( + session_id=session_id, + ) + + # 3. Yield history first, then stream — dedupe by event.id + seen = set() + for ev in history.data: + seen.add(ev.id) + yield ev + for ev in stream: + if ev.id not in seen: + seen.add(ev.id) + yield ev +``` + +### Message queuing + +**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups: + +```ts +// All three go into one session; agent processes them in order +await sendMessage(sessionId, "Summarize the README"); +await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide"); +await sendMessage(sessionId, "And compare the two"); +// Stream once — agent responds to all three as a coherent turn +``` + +Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()` + +### Interrupt + +An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands: + +```ts +await client.beta.sessions.events.send(sessionId, { + events: [{ type: 'interrupt' }], +}); +``` + +The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. + +> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs. + +### Event payloads + +some events carry useful metadata beyond the status change itself: + +`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user. +```json +{ + "id": "sevt_456", + "processed_at": "2026-04-07T04:27:43.197Z", + "stop_reason": { + "event_ids": [ + "sevt_123" + ], + "type": "requires_action" + }, + "type": "status_idle" +} +``` + +`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis: + +```json +{ + "type": "span.model_request_end", + "id": "sevt_456", + "is_error": false, + "model_request_start_id": "sevt_123", + "model_usage": { + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 6656, + "input_tokens": 3571, + "output_tokens": 727 + }, + "processed_at": "2026-04-07T04:11:32.189Z" +} +``` + +**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed: + +```json +{ + "id": "sevt_abc123", + "processed_at": "2026-03-24T14:05:15.787Z", + "type": "agent.thread_context_compacted" +} +``` + +### Archive + +When done with a session, archive it to free resources: + +```ts +await client.beta.sessions.archive(sessionId); +``` + + diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-onboarding.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-onboarding.md new file mode 100644 index 0000000..9ee9501 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-onboarding.md @@ -0,0 +1,114 @@ +# Managed Agents — Onboarding Flow + +> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions. + +Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code. + +> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference. + +--- + +Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you. + +**What you supply:** +- **An agent config** — tools, skills, model, system prompt. Reusable and versioned. +- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents. + +Each run of the agent is a **session**. + +--- + +## 1. Know or explore? + +Ask the user: + +> Do you already know the agent you want to build, or would you like to explore some common patterns first? + +### Explore path — show the patterns + +Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ. + +| Pattern | Trigger | Example | +|---|---|---| +| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete? +| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete? +| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI | +| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard | + +Ask which shape fits, then continue with the Know path using it as the reference. + +### Know path — configure template + +Three rounds. Batch the questions in each round; don't ask them one at a time. + +**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination): + +| Type | What it is | How to guide | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. | +| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. | +| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. | + +**Round B — Skills, files, and repos.** What the agent has on hand when it starts. + +*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 64 per agent. +- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name. +- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API. + +*GitHub repositories* — any repos the agent needs on-disk? For each: +- [ ] Repo URL (`https://github.com/org/repo`) +- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo) +- [ ] Optional `mount_path` (defaults to `/workspace/`) and `checkout` (branch or SHA) + +Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories. + +> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool. + +*Files* — any local files to seed the session with? For each: +- [ ] Upload via the Files API → persist `file_id` +- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only) + +Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API. + +**Round C — Environment + identity:** +- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.) +- [ ] Name? +- [ ] Job (one or two sentences — becomes the system prompt)? +- [ ] Model? (default `claude-opus-4-6`) + +--- + +## 2. Set up the session + +Per-run. Points at the agent + environment, attaches credentials, kicks off. + +**Vault credentials** (if the agent declared MCP servers): +- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`) + +Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults. + +**Kickoff:** +- [ ] First message to the agent? + +Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope: session_id})`. + +--- + +## 3. Emit the code + +Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection): + +**Block 1 — Setup (run once, store the IDs):** +1. `environments.create()` → persist `env_id` +2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version` + +Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env` + +**Block 2 — Runtime (run on every invocation):** +1. Load `env_id` + `agent_id` from config/env +2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])` +3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`) + +> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`. + +Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names. diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-overview.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-overview.md new file mode 100644 index 0000000..bbb0a89 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-overview.md @@ -0,0 +1,61 @@ +# Managed Agents — Overview + +Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in. + +## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run) + +**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run. + +Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs. + +| Step | Call | Frequency | +|---|---|---| +| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. | +| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. | + +If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only. + +**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`. + +**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. + +## Beta Headers + +Managed Agents is in beta. The SDK sets required beta headers automatically: + +| Beta Header | What it enables | +| ------------------------------ | ---------------------------------------------------- | +| `managed-agents-2026-04-01` | Agents, Environments, Sessions, Events, Session Resources, Vaults, Credentials | +| `skills-2025-10-02` | Skills API (for managing custom skill definitions) | +| `files-api-2025-04-14` | Files API for file uploads | + +**Note: do not intermix beta headers** — If you need to upload a skill or file via the Skills API or Files API you will need to use the appropriate beta header as listed above. However, you do NOT need to inlude either the Skills or Files beta header when using any of the Managed Agents endpints listed in row 1 above. Do NOT include intermix beta headers and prefer to use the Skills or Files beta headers when using their specific endpoints. + + +## Reading Guide + +| User wants to... | Read these files | +| -------------------------------------- | ------------------------------------------------------- | +| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code | +| Understand how the API works | `shared/managed-agents-core.md` | +| See the full endpoint reference | `shared/managed-agents-api-reference.md` | +| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file | +| Update/version an agent | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create | +| Create a session | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` | +| Configure tools and permissions | `shared/managed-agents-tools.md` | +| Set up MCP servers | `shared/managed-agents-tools.md` (MCP Servers section) | +| Stream events / handle tool_use | `shared/managed-agents-events.md` + language file | +| Set up environments | `shared/managed-agents-environments.md` + language file | +| Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) | +| Store MCP credentials | `shared/managed-agents-tools.md` (Vaults section) | + +## Common Pitfalls + +- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example. +- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility. +- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token. +- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time. +- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream. +- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. +- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message. +- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type. diff --git a/junie/versions/2206.4/skills/claude-api/shared/managed-agents-tools.md b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-tools.md new file mode 100644 index 0000000..cce75c9 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/managed-agents-tools.md @@ -0,0 +1,301 @@ +# Managed Agents — Tools & Skills + +## Tools + +### Server tools vs client tools + +| Type | Who runs it | How it works | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. | +| **MCP tools** (`mcp_toolset`) | Anthropic, on the session's container | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. | +| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. | + +**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed. + +**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting. + +### Agent Toolset + +The `agent_toolset_20260401` provides these built-in tools: + +| Tool | Description | +| ---------------------- | ---------------------------------------- | +| `bash` | Execute bash commands in a shell session | +| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks | +| `write` | Write a file to the local filesystem | +| `edit` | Perform string replacement in a file | +| `glob` | Fast file pattern matching using glob patterns | +| `grep` | Text search using regex patterns | +| `web_fetch` | Fetch content from a URL | +| `web_search` | Search the web for information | + +Enable the full toolset: + +```json +{ + "tools": [ + { "type": "agent_toolset_20260401" } + ] +} +``` + +### Per-Tool Configuration + +Override defaults for individual tools. This example enables everything except bash: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] +} +``` + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"agent_toolset_20260401"` | +| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` | +| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` | + +### Permission Policies + +Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools. + +| Policy | Behavior | +|---|---| +| `always_allow` | Tool executes automatically (default) | +| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event | + +```json +{ + "type": "agent_toolset_20260401", + "default_config": { + "enabled": true, + "permission_policy": { "type": "always_allow" } + }, + "configs": [ + { "name": "bash", "permission_policy": { "type": "always_ask" } } + ] +} +``` + +**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event: + +```json +{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" } +{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" } +``` + +The optional `message` on a deny is delivered to the agent so it can adjust its approach. + +To enable only specific tools, flip the default off and opt-in per tool: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": false }, + "configs": [ + { "name": "bash", "enabled": true }, + { "name": "read", "enabled": true } + ] + } + ] +} +``` + +### Custom Tools (Client-Side) + +Custom tools are executed by **your application**, not Anthropic. The flow: + +1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs +2. Session goes `idle` waiting for you +3. Your application executes the tool +4. You send back a `user.custom_tool_result` event with the output +5. Session resumes `running` + +No permission policy needed — you're the one executing. + +```json +{ + "tools": [ + { + "type": "custom", + "name": "get_weather", + "description": "Fetch current weather for a city.", + "input_schema": { + "type": "object", + "properties": { + "city": { "type": "string", "description": "City name" } + }, + "required": ["city"] + } + } + ] +} +``` + +### MCP Servers + +MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:** + +1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field. +2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create. + +This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL. + +**Agent side — declare servers (no auth):** + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"url"` | +| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` | +| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) | + +```json +{ + "mcp_servers": [ + { "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" } + ], + "tools": [ + { "type": "mcp_toolset", "mcp_server_name": "linear" } + ] +} +``` + +**Session side — attach vault:** + +```json +{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] +} +``` + +> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form. + +> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems. + +### Vaults — the MCP credential store + +**Vaults** store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers in the launch SDK. + +> Formerly known internally as TATs (Tool/Tenant Access Tokens). + +**Flow:** + +1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model +2. Add MCP credentials to it (`client.beta.vaults.credentials.create(...)`) — each credential is tied to one MCP server URL +3. Reference the vault on session create via `vault_ids: ["vlt_..."]` +4. Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools + +**Credential shape**: + +```json +{ + "display_name": "Notion (workspace-foo)", + "auth": { + "type": "mcp_oauth", + "mcp_server_url": "https://mcp.notion.com/mcp", + "access_token": "", + "expires_at": "2026-04-02T14:00:00Z", + "refresh": { + "refresh_token": "", + "client_id": "", + "token_endpoint": "https://api.notion.com/v1/oauth/token", + "token_endpoint_auth": { "type": "none" } + } + } +} +``` + +The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union: + +| `type` | Shape | Use when | +|---|---|---| +| `"none"` | `{type: "none"}` | Public OAuth client (no secret) | +| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth | +| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body | + +Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access. + +> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there. + +**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected"). + +--- + +## Skills + +Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. + +Two types — both work the same way; the agent automatically uses them when relevant to the task at hand: + +| Type | What it is | +|---|---| +| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). | +| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. | + +**Max 64 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`. + +### Enabling skills on a session + +Skills are attached to the **agent** definition via `agents.create()`: + +```ts +const agent = await client.beta.agents.create( + { + name: "Financial Agent", + model: "claude-opus-4-6", + system: "You are a financial analysis agent.", + skills: [ + { type: "anthropic", skill_id: "xlsx" }, + { type: "custom", skill_id: "skill_abc123", version: "latest" }, + ], + } +); +``` + +Python: + +```python +agent = client.beta.agents.create( + name="Financial Agent", + model="claude-opus-4-6", + system="You are a financial analysis agent.", + skills=[ + {"type": "anthropic", "skill_id": "xlsx"}, + {"type": "custom", "skill_id": "skill_abc123", "version": "latest"}, + ] +) +``` + +**Skill reference fields:** + +| Field | Anthropic skill | Custom skill | +|---|---|---| +| `type` | `"anthropic"` | `"custom"` | +| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) | +| `version` | — | `"latest"` or a specific version number | + +### Skills API + +| Operation | Method | Path | +| --------------------- | -------- | ----------------------------------------------- | +| Create Skill | `POST` | `/v1/skills` | +| List Skills | `GET` | `/v1/skills` | +| Get Skill | `GET` | `/v1/skills/{id}` | +| Delete Skill | `DELETE` | `/v1/skills/{id}` | +| Create Version | `POST` | `/v1/skills/{id}/versions` | +| List Versions | `GET` | `/v1/skills/{id}/versions` | +| Get Version | `GET` | `/v1/skills/{id}/versions/{version}` | +| Delete Version | `DELETE` | `/v1/skills/{id}/versions/{version}` | + diff --git a/junie/versions/2206.4/skills/claude-api/shared/models.md b/junie/versions/2206.4/skills/claude-api/shared/models.md new file mode 100644 index 0000000..6344d60 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/models.md @@ -0,0 +1,119 @@ +# Claude Model Catalog + +**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below). + +## Programmatic Model Discovery + +For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime. + +```python +m = client.models.retrieve("claude-opus-4-6") +m.id # "claude-opus-4-6" +m.display_name # "Claude Opus 4.6" +m.max_input_tokens # context window (int) +m.max_tokens # max output tokens (int) + +# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf +caps = m.capabilities +caps["image_input"]["supported"] # vision +caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking +caps["effort"]["max"]["supported"] # effort: max (also low/medium/high) +caps["structured_outputs"]["supported"] +caps["context_management"]["compact_20260112"]["supported"] + +# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data +[m for m in client.models.list() + if m.capabilities["thinking"]["types"]["adaptive"]["supported"] + and m.max_input_tokens >= 200_000] +``` + +Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration. + +### Raw HTTP + +```bash +curl https://api.anthropic.com/v1/models/claude-opus-4-6 \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" +``` + +```json +{ + "id": "claude-opus-4-6", + "display_name": "Claude Opus 4.6", + "max_input_tokens": 1000000, + "max_tokens": 128000, + "capabilities": { + "image_input": {"supported": true}, + "structured_outputs": {"supported": true}, + "thinking": {"supported": true, "types": {"enabled": {"supported": true}, "adaptive": {"supported": true}}}, + "effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}}, + … + } +} +``` + +## Current Models (recommended) + +| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status | +|-------------------|---------------------|-------------------------------|----------------|------------|--------| +| Claude Opus 4.6 | `claude-opus-4-6` | — | 200K (1M beta) | 128K | Active | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 200K (1M beta) | 64K | Active | +| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active | + +### Model Descriptions + +- **Claude Opus 4.6** — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via `context-1m-2025-08-07` header. +- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via `context-1m-2025-08-07` header. 64K max output tokens. +- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks. + +## Legacy Models (still active) + +| Friendly Name | Alias (use this) | Full ID | Status | +|-------------------|---------------------|-------------------------------|--------| +| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active | +| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Active | +| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active | +| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Active | +| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Active | + +## Deprecated Models (retiring soon) + +| Friendly Name | Alias (use this) | Full ID | Status | Retires | +|-------------------|---------------------|-------------------------------|------------|--------------| +| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | Apr 19, 2026 | + +## Retired Models (no longer available) + +| Friendly Name | Full ID | Retired | +|-------------------|-------------------------------|-------------| +| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 | +| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 | +| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 | +| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 | +| Claude 2.1 | `claude-2.1` | Jul 21, 2025 | +| Claude 2.0 | `claude-2.0` | Jul 21, 2025 | + +## Resolving User Requests + +When a user asks for a model by name, use this table to find the correct model ID: + +| User says... | Use this model ID | +|-------------------------------------------|--------------------------------| +| "opus", "most powerful" | `claude-opus-4-6` | +| "opus 4.6" | `claude-opus-4-6` | +| "opus 4.5" | `claude-opus-4-5` | +| "opus 4.1" | `claude-opus-4-1` | +| "opus 4", "opus 4.0" | `claude-opus-4-0` | +| "sonnet", "balanced" | `claude-sonnet-4-6` | +| "sonnet 4.6" | `claude-sonnet-4-6` | +| "sonnet 4.5" | `claude-sonnet-4-5` | +| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` | +| "sonnet 3.7" | Retired — suggest `claude-sonnet-4-5` | +| "sonnet 3.5" | Retired — suggest `claude-sonnet-4-5` | +| "haiku", "fast", "cheap" | `claude-haiku-4-5` | +| "haiku 4.5" | `claude-haiku-4-5` | +| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` | +| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` | diff --git a/junie/versions/2206.4/skills/claude-api/shared/prompt-caching.md b/junie/versions/2206.4/skills/claude-api/shared/prompt-caching.md new file mode 100644 index 0000000..2bd9bca --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/prompt-caching.md @@ -0,0 +1,171 @@ +# Prompt Caching — Design & Optimization + +This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc. + +## The one invariant everything follows from + +**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.** + +The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N. + +Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together. + +Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help. + +--- + +## Workflow for optimizing existing code + +When asked to add or optimize caching: + +1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them. +2. **Classify each input by stability:** + - Never changes → belongs early in the prompt, before any breakpoint + - Changes per-session → belongs after the global prefix, cache per-session + - Changes per-turn → belongs at the end, after the last breakpoint + - Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end** +3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers. +4. **Place breakpoints at stability boundaries.** See placement patterns below. +5. **Audit for silent invalidators.** See anti-patterns table. + +--- + +## Placement patterns + +### Large system prompt shared across many requests + +Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together. + +```json +"system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} +] +``` + +### Multi-turn conversations + +Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows. + +```json +// Last content block of the last user turn +messages[-1].content[-1].cache_control = {"type": "ephemeral"} +``` + +### Shared prefix, varying suffix + +Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read. + +```json +"messages": [{"role": "user", "content": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": ""} // no marker — differs every time +]}] +``` + +### Prompts that change from the beginning every time + +Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off. + +--- + +## Architectural guidance + +These are the decisions that matter more than marker placement. Fix these first. + +**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context as a user or assistant message later in `messages`. A message at turn 5 invalidates nothing before turn 5. + +**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name). + +**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end. + +--- + +## Silent invalidators + +When reviewing code, grep for these inside anything that feeds the prompt prefix: + +| Pattern | Why it breaks caching | +|---|---| +| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request | +| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique | +| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ | +| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing | +| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix | +| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users | + +Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing. + +--- + +## API reference + +```json +"cache_control": {"type": "ephemeral"} // 5-minute TTL (default) +"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL +``` + +- Max **4** `cache_control` breakpoints per request. +- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`). +- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement. +- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`: + +| Model | Minimum | +|---|---:| +| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens | +| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens | +| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens | + +A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.6. + +**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off. + +--- + +## Verifying cache hits + +The response `usage` object reports cache activity: + +| Field | Meaning | +|---|---| +| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) | +| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) | +| `input_tokens` | Tokens processed at full price (not cached) | + +If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it. + +**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field. + +Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java). + +--- + +## Invalidation hierarchy + +Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below: + +| Change | Tools cache | System cache | Messages cache | +|---|:---:|:---:|:---:| +| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ | +| Model switch | ❌ | ❌ | ❌ | +| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ | +| System prompt content | ✅ | ❌ | ❌ | +| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ | +| Message content | ✅ | ✅ | ❌ | + +Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild. + +--- + +## 20-block lookback window + +Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses. + +Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block. + +--- + +## Concurrent-request timing + +A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing. + +For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote. diff --git a/junie/versions/2206.4/skills/claude-api/shared/tool-use-concepts.md b/junie/versions/2206.4/skills/claude-api/shared/tool-use-concepts.md new file mode 100644 index 0000000..65d9637 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/shared/tool-use-concepts.md @@ -0,0 +1,327 @@ +# Tool Use Concepts + +This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`. + +## User-Defined Tools + +### Tool Definition Structure + +> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support. + +Each tool requires a name, description, and JSON Schema for its inputs: + +```json +{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City and state, e.g., San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "Temperature unit" + } + }, + "required": ["location"] + } +} +``` + +**Best practices for tool definitions:** + +- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`) +- Write detailed descriptions — Claude uses these to decide when to use the tool +- Include descriptions for each property +- Use `enum` for parameters with a fixed set of values +- Mark truly required parameters in `required`; make others optional with defaults + +--- + +### Tool Choice Options + +Control when Claude uses tools: + +| Value | Behavior | +| --------------------------------- | --------------------------------------------- | +| `{"type": "auto"}` | Claude decides whether to use tools (default) | +| `{"type": "any"}` | Claude must use at least one tool | +| `{"type": "tool", "name": "..."}` | Claude must use the specified tool | +| `{"type": "none"}` | Claude cannot use tools | + +Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response. + +--- + +### Tool Runner vs Manual Loop + +**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. + +**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`. + +**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically. + +```python +# Handle pause_turn in your agentic loop +if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_query}, + {"role": "assistant", "content": response.content}, + ] + # Make another API request — server resumes automatically + response = client.messages.create( + model="claude-opus-4-6", messages=messages, tools=tools + ) +``` + +Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons` + +> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution. + +--- + +### Handling Tool Results + +When Claude uses a tool, the response contains a `tool_use` block. You must: + +1. Execute the tool with the provided input +2. Send the result back in a `tool_result` message +3. Continue the conversation + +**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification. + +**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message. + +--- + +## Server-Side Tools: Code Execution + +The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest. + +### Key Facts + +- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk) +- No internet access (fully sandboxed) +- Python 3.11 with data science libraries pre-installed +- Containers persist for 30 days and can be reused across requests +- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization + +### Tool Definition + +The tool requires no schema — just declare it in the `tools` array: + +```json +{ + "type": "code_execution_20260120", + "name": "code_execution" +} +``` + +Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files). + +### Pre-installed Python Libraries + +- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels +- **Visualization**: matplotlib, seaborn +- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx +- **Math**: sympy, mpmath +- **Utilities**: tqdm, python-dateutil, pytz, sqlite3 + +Additional packages can be installed at runtime via `pip install`. + +### Supported File Types for Upload + +| Type | Extensions | +| ------ | ---------------------------------- | +| Data | CSV, Excel (.xlsx/.xls), JSON, XML | +| Images | JPEG, PNG, GIF, WebP | +| Text | .txt, .md, .py, .js, etc. | + +### Container Reuse + +Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests. + +### Response Structure + +The response contains interleaved text and tool result blocks: + +- `text` — Claude's explanation +- `server_tool_use` — What Claude is doing +- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure) +- `text_editor_code_execution_tool_result` — File operation results + +> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory. + +--- + +## Server-Side Tools: Web Search and Web Fetch + +Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically. + +### Tool Definitions + +```json +[ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } +] +``` + +### Dynamic Filtering (Opus 4.6 / Sonnet 4.6) + +The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header. + +```json +{ + "tools": [ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } + ] +} +``` + +Without dynamic filtering, the previous `web_search_20250305` version is also available. + +> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model. + +--- + +## Server-Side Tools: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again. + +Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling` + +--- + +## Server-Side Tools: Tool Search + +The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool` + +--- + +## Skills + +Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills` + +--- + +## Tool Use Examples + +You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use` + +--- + +## Server-Side Tools: Computer Use + +Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview` + +--- + +## Context Editing + +Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing` + +--- + +## Client-Side Tools: Memory + +The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions. + +### Key Facts + +- Client-side tool — you control storage via your implementation +- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename` +- Operates on files in a `/memories` directory +- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend + +> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers. + +For full implementation examples, use WebFetch: + +- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` + +--- + +## Structured Outputs + +Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation. + +Two features are available: + +- **JSON outputs** (`output_config.format`): Control Claude's response format +- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas + +**Supported models:** Claude Opus 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. + +> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter. + +### JSON Schema Limitations + +**Supported:** + +- Basic types: object, array, string, integer, number, boolean, null +- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def` +- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` +- `additionalProperties: false` (required for all objects) + +**Not supported:** + +- Recursive schemas +- Numerical constraints (`minimum`, `maximum`, `multipleOf`) +- String constraints (`minLength`, `maxLength`) +- Complex array constraints +- `additionalProperties` set to anything other than `false` + +The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side. + +### Important Notes + +- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache. +- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema. +- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`. +- **Incompatible with**: Citations (returns 400 error), message prefilling. +- **Works with**: Batches API, streaming, token counting, extended thinking. + +--- + +## Tips for Effective Tool Use + +1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools +2. **Use specific tool names**: `get_current_weather` is better than `weather` +3. **Validate inputs**: Always validate tool inputs before execution +4. **Handle errors gracefully**: Return informative error messages so Claude can adapt +5. **Limit tool count**: Too many tools can confuse the model — keep the set focused +6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios + +For detailed tool use documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/claude-api/README.md b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/README.md new file mode 100644 index 0000000..3847621 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/README.md @@ -0,0 +1,333 @@ +# Claude API — TypeScript + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Basic Message Request + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [{ role: "user", content: "What is the capital of France?" }], +}); +// response.content is ContentBlock[] — a discriminated union. Narrow by .type +// before accessing .text (TypeScript will error on content[0].text without this). +for (const block of response.content) { + if (block.type === "text") { + console.log(block.text); + } +} +``` + +--- + +## System Prompts + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: + "You are a helpful coding assistant. Always provide examples in Python.", + messages: [{ role: "user", content: "How do I read a JSON file?" }], +}); +``` + +--- + +## Vision (Images) + +### URL + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "url", url: "https://example.com/image.png" }, + }, + { type: "text", text: "Describe this image" }, + ], + }, + ], +}); +``` + +### Base64 + +```typescript +import fs from "fs"; + +const imageData = fs.readFileSync("image.png").toString("base64"); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "base64", media_type: "image/png", data: imageData }, + }, + { type: "text", text: "What's in this image?" }, + ], + }, + ], +}); +``` + +--- + +## Prompt Caching + +**Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block + system: "You are an expert on this large document...", + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral" }, // default TTL is 5 minutes + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// With explicit TTL (time-to-live) +const response2 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Verifying Cache Hits + +```typescript +console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost) +console.log(response.usage.cache_read_input_tokens); // tokens served from cache (~0.1x cost) +console.log(response.usage.input_tokens); // uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `Date.now()` or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```typescript +// Opus 4.6: adaptive thinking (recommended) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + thinking: { type: "adaptive" }, + output_config: { effort: "high" }, // low | medium | high | max + messages: [ + { role: "user", content: "Solve this math problem step by step..." }, + ], +}); + +for (const block of response.content) { + if (block.type === "thinking") { + console.log("Thinking:", block.thinking); + } else if (block.type === "text") { + console.log("Response:", block.text); + } +} +``` + +--- + +## Error Handling + +Use the SDK's typed exception classes — never check error messages with string matching: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.BadRequestError) { + console.error("Bad request:", error.message); + } else if (error instanceof Anthropic.AuthenticationError) { + console.error("Invalid API key"); + } else if (error instanceof Anthropic.RateLimitError) { + console.error("Rate limited - retry later"); + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} +``` + +All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference. + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array: + +```typescript +const messages: Anthropic.MessageParam[] = [ + { role: "user", content: "My name is Alice." }, + { role: "assistant", content: "Hello Alice! Nice to meet you." }, + { role: "user", content: "What's my name?" }, +]; + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: messages, +}); +``` + +**Rules:** + +- Consecutive same-role messages are allowed — the API combines them into a single turn +- First message must be `user` +- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const messages: Anthropic.Beta.BetaMessageParam[] = []; + +async function chat(userMessage: string): Promise { + messages.push({ role: "user", content: userMessage }); + + const response = await client.beta.messages.create({ + betas: ["compact-2026-01-12"], + model: "claude-opus-4-6", + max_tokens: 16000, + messages, + context_management: { + edits: [{ type: "compact_20260112" }], + }, + }); + + // Append full content — compaction blocks must be preserved + messages.push({ role: "assistant", content: response.content }); + + const textBlock = response.content.find( + (b): b is Anthropic.Beta.BetaTextBlock => b.type === "text", + ); + return textBlock?.text ?? ""; +} + +// Compaction triggers automatically when context grows large +console.log(await chat("Help me build a Python web scraper")); +console.log(await chat("Add support for JavaScript-rendered pages")); +console.log(await chat("Now add rate limiting and error handling")); +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +| --------------- | --------------------------------------------------------------- | +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```typescript +// Automatic caching (simplest — caches the last cacheable block) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, + system: largeDocumentText, // e.g., 50KB of context + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// First request: full cost +// Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Use Token Counting Before Requests + +```typescript +const countResponse = await client.messages.countTokens({ + model: "claude-opus-4-6", + messages: messages, + system: system, +}); + +const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens +console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`); +``` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/claude-api/batches.md b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/batches.md new file mode 100644 index 0000000..e7a9fa3 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/batches.md @@ -0,0 +1,106 @@ +# Message Batches API — TypeScript + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const messageBatch = await client.messages.batches.create({ + requests: [ + { + custom_id: "request-1", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Summarize climate change impacts" }, + ], + }, + }, + { + custom_id: "request-2", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Explain quantum computing basics" }, + ], + }, + }, + ], +}); + +console.log(`Batch ID: ${messageBatch.id}`); +console.log(`Status: ${messageBatch.processing_status}`); +``` + +--- + +## Poll for Completion + +```typescript +let batch; +while (true) { + batch = await client.messages.batches.retrieve(messageBatch.id); + if (batch.processing_status === "ended") break; + console.log( + `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`, + ); + await new Promise((resolve) => setTimeout(resolve, 60_000)); +} + +console.log("Batch complete!"); +console.log(`Succeeded: ${batch.request_counts.succeeded}`); +console.log(`Errored: ${batch.request_counts.errored}`); +``` + +--- + +## Retrieve Results + +```typescript +for await (const result of await client.messages.batches.results( + messageBatch.id, +)) { + switch (result.result.type) { + case "succeeded": + console.log( + `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`, + ); + break; + case "errored": + if (result.result.error.type === "invalid_request") { + console.log(`[${result.custom_id}] Validation error - fix and retry`); + } else { + console.log(`[${result.custom_id}] Server error - safe to retry`); + } + break; + case "expired": + console.log(`[${result.custom_id}] Expired - resubmit`); + break; + } +} +``` + +--- + +## Cancel a Batch + +```typescript +const cancelled = await client.messages.batches.cancel(messageBatch.id); +console.log(`Status: ${cancelled.processing_status}`); // "canceling" +``` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/claude-api/files-api.md b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/files-api.md new file mode 100644 index 0000000..5f1223d --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/files-api.md @@ -0,0 +1,98 @@ +# Files API — TypeScript + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import fs from "fs"; + +const client = new Anthropic(); + +const uploaded = await client.beta.files.upload({ + file: await toFile(fs.createReadStream("report.pdf"), undefined, { + type: "application/pdf", + }), + betas: ["files-api-2025-04-14"], +}); + +console.log(`File ID: ${uploaded.id}`); +console.log(`Size: ${uploaded.size_bytes} bytes`); +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```typescript +const response = await client.beta.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { type: "text", text: "Summarize the key findings in this report." }, + { + type: "document", + source: { type: "file", file_id: uploaded.id }, + title: "Q4 Report", + citations: { enabled: true }, + }, + ], + }, + ], + betas: ["files-api-2025-04-14"], +}); + +console.log(response.content[0].text); +``` + +--- + +## Manage Files + +### List Files + +```typescript +const files = await client.beta.files.list({ + betas: ["files-api-2025-04-14"], +}); +for (const f of files.data) { + console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`); +} +``` + +### Delete a File + +```typescript +await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", { + betas: ["files-api-2025-04-14"], +}); +``` + +### Download a File + +```typescript +const response = await client.beta.files.download( + "file_011CNha8iCJcU1wXNR6q4V8w", + { betas: ["files-api-2025-04-14"] }, +); +const content = Buffer.from(await response.arrayBuffer()); +await fs.promises.writeFile("output.txt", content); +``` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/claude-api/streaming.md b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/streaming.md new file mode 100644 index 0000000..f6a450f --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/streaming.md @@ -0,0 +1,178 @@ +# Streaming — TypeScript + +## Quick Start + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a story" }], +}); + +for await (const event of stream) { + if ( + event.type === "content_block_delta" && + event.delta.type === "text_delta" + ) { + process.stdout.write(event.delta.text); + } +} +``` + +--- + +## Handling Different Content Types + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + thinking: { type: "adaptive" }, + messages: [{ role: "user", content: "Analyze this problem" }], +}); + +for await (const event of stream) { + switch (event.type) { + case "content_block_start": + switch (event.content_block.type) { + case "thinking": + console.log("\n[Thinking...]"); + break; + case "text": + console.log("\n[Response:]"); + break; + } + break; + case "content_block_delta": + switch (event.delta.type) { + case "thinking_delta": + process.stdout.write(event.delta.thinking); + break; + case "text_delta": + process.stdout.write(event.delta.text); + break; + } + break; + } +} +``` + +--- + +## Streaming with Tool Use (Tool Runner) + +Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + }), + run: async ({ location }) => `72°F and sunny in ${location}`, +}); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools: [getWeather], + messages: [ + { role: "user", content: "What's the weather in Paris and London?" }, + ], + stream: true, +}); + +// Outer loop: each tool runner iteration +for await (const messageStream of runner) { + // Inner loop: stream events for this iteration + for await (const event of messageStream) { + switch (event.type) { + case "content_block_delta": + switch (event.delta.type) { + case "text_delta": + process.stdout.write(event.delta.text); + break; + case "input_json_delta": + // Tool input being streamed + break; + } + break; + } + } +} +``` + +--- + +## Getting the Final Message + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Hello" }], +}); + +for await (const event of stream) { + // Process events... +} + +const finalMessage = await stream.finalMessage(); +console.log(`Tokens used: ${finalMessage.usage.output_tokens}`); +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `process.stdout.write()` for immediate display +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally +5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates +6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events +7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop + +## Raw SSE Format + +If using raw HTTP (not SDKs), the stream returns Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/claude-api/tool-use.md b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/tool-use.md new file mode 100644 index 0000000..28525c6 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/claude-api/tool-use.md @@ -0,0 +1,527 @@ +# Tool Use — TypeScript + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the TypeScript SDK. + +Use `betaZodTool` with Zod schemas to define tools with a `run` function, then pass them to `client.beta.messages.toolRunner()`: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + unit: z.enum(["celsius", "fahrenheit"]).optional(), + }), + run: async (input) => { + // Your implementation here + return `72°F and sunny in ${input.location}`; + }, +}); + +// The tool runner handles the agentic loop and returns the final message +const finalMessage = await client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [getWeather], + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +console.log(finalMessage.content); +``` + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via Zod schemas +- Tool schemas are generated automatically from Zod definitions +- Iteration stops automatically when Claude has no more tool calls + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval): + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; // Your tool definitions +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: messages, + }); + + if (response.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (response.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: response.content }); + continue; + } + + const toolUseBlocks = response.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: response.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +### Streaming Manual Loop + +Use `client.messages.stream()` + `finalMessage()` instead of `.create()` when you need streaming within a manual loop. Text deltas are streamed on each iteration; `finalMessage()` collects the complete `Message` so you can inspect `stop_reason` and extract tool-use blocks: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools, + messages, + }); + + // Stream text deltas on each iteration + stream.on("text", (delta) => { + process.stdout.write(delta); + }); + + // finalMessage() resolves with the complete Message — no need to + // manually wire up .on("message") / .on("error") / .on("abort") + const message = await stream.finalMessage(); + + if (message.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (message.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: message.content }); + continue; + } + + const toolUseBlocks = message.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: message.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +> **Important:** Don't wrap `.on()` events in `new Promise()` to collect the final message — use `stream.finalMessage()` instead. The SDK handles all error/abort/completion states internally. + +> **Error handling in the loop:** Use the SDK's typed exceptions (e.g., `Anthropic.RateLimitError`, `Anthropic.APIError`) — see [Error Handling](./README.md#error-handling) for examples. Don't check error messages with string matching. + +> **SDK types:** Use `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.ToolUseBlock`, `Anthropic.ToolResultBlockParam`, `Anthropic.Message`, etc. for all API-related data structures. Don't redefine equivalent interfaces. + +--- + +## Handling Tool Results + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +for (const block of response.content) { + if (block.type === "tool_use") { + const result = await executeTool(block.name, block.input); + + const followup = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [ + { role: "user", content: "What's the weather in Paris?" }, + { role: "assistant", content: response.content }, + { + role: "user", + content: [ + { type: "tool_result", tool_use_id: block.id, content: result }, + ], + }, + ], + }); + } +} +``` + +--- + +## Tool Choice + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + tool_choice: { type: "tool", name: "get_weather" }, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); +``` + +--- + +## Server-Side Tools + +Version-suffixed `type` literals; `name` is fixed per interface. Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322. + +**Don't type-annotate as `Tool[]`** — `Tool` is just the custom-tool variant. Let structural typing infer from the `tools` param, or annotate as `Anthropic.Messages.ToolUnion[]` if you must: + +```typescript +// ✓ let inference work — no annotation +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [ + { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, + { type: "bash_20250124", name: "bash" }, + { type: "web_search_20260209", name: "web_search" }, + { type: "code_execution_20260120", name: "code_execution" }, + ], + messages: [{ role: "user", content: "..." }], +}); + +// ✗ this is a TS2352 — Tool is the CUSTOM tool variant only +// const tools: Anthropic.Tool[] = [{ type: "text_editor_20250728", ... }] +``` + +| Interface | `name` | `type` | +|---|---|---| +| `ToolTextEditor20250124` | `str_replace_editor` | `text_editor_20250124` | +| `ToolTextEditor20250429` | `str_replace_based_edit_tool` | `text_editor_20250429` | +| `ToolTextEditor20250728` | `str_replace_based_edit_tool` | `text_editor_20250728` | +| `ToolBash20250124` | `bash` | `bash_20250124` | +| `WebSearchTool20260209` | `web_search` | `web_search_20260209` | +| `WebFetchTool20260209` | `web_fetch` | `web_fetch_20260209` | +| `CodeExecutionTool20260120` | `code_execution` | `code_execution_20260120` | + +**Don't mix beta and non-beta types**: if you call `client.beta.messages.create()`, the response `content` is `BetaContentBlock[]` — you cannot pass that to a non-beta `ContentBlockParam[]` without narrowing each element. + +--- + + +## Code Execution + +### Basic Usage + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +### Reading Local Files (ESM note) + +`__dirname` doesn't exist in ES modules. For script-relative paths use `import.meta.url`: + +```typescript +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pdfBytes = readFileSync(join(__dirname, "sample.pdf")); +``` + +Or use a CWD-relative path if the script runs from a known directory: `readFileSync("./sample.pdf")`. + +### Upload Files for Analysis + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import { createReadStream } from "fs"; + +const client = new Anthropic(); + +// 1. Upload a file +const uploaded = await client.beta.files.upload({ + file: await toFile(createReadStream("sales_data.csv"), undefined, { + type: "text/csv", + }), + betas: ["files-api-2025-04-14"], +}); + +// 2. Pass to code execution +// Code execution is GA; Files API is still beta (pass via RequestOptions) +const response = await client.messages.create( + { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "Analyze this sales data. Show trends and create a visualization.", + }, + { type: "container_upload", file_id: uploaded.id }, + ], + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], + }, + { headers: { "anthropic-beta": "files-api-2025-04-14" } }, +); +``` + +### Retrieve Generated Files + +```typescript +import path from "path"; +import fs from "fs"; + +const OUTPUT_DIR = "./claude_outputs"; +await fs.promises.mkdir(OUTPUT_DIR, { recursive: true }); + +for (const block of response.content) { + if (block.type === "bash_code_execution_tool_result") { + const result = block.content; + if (result.type === "bash_code_execution_result" && result.content) { + for (const fileRef of result.content) { + if (fileRef.type === "bash_code_execution_output") { + const metadata = await client.beta.files.retrieveMetadata( + fileRef.file_id, + ); + const downloadResponse = await client.beta.files.download(fileRef.file_id); + const fileBytes = Buffer.from(await downloadResponse.arrayBuffer()); + const safeName = path.basename(metadata.filename); + if (!safeName || safeName === "." || safeName === "..") { + console.warn(`Skipping invalid filename: ${metadata.filename}`); + continue; + } + const outputPath = path.join(OUTPUT_DIR, safeName); + await fs.promises.writeFile(outputPath, fileBytes); + console.log(`Saved: ${outputPath}`); + } + } + } + } +} +``` + +### Container Reuse + +```typescript +// First request: set up environment +const response1 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Install tabulate and create data.json with sample user data", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); + +// Reuse container +// container is nullable — set only when using server-side code execution +const containerId = response1.container!.id; + +const response2 = await client.messages.create({ + container: containerId, + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Read data.json and display as a formatted table", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +--- + +## Memory Tool + +### Basic Usage + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Remember that my preferred language is TypeScript.", + }, + ], + tools: [{ type: "memory_20250818", name: "memory" }], +}); +``` + +### SDK Memory Helper + +Use `betaMemoryTool` with a `MemoryToolHandlers` implementation: + +```typescript +import { + betaMemoryTool, + type MemoryToolHandlers, +} from "@anthropic-ai/sdk/helpers/beta/memory"; + +const handlers: MemoryToolHandlers = { + async view(command) { ... }, + async create(command) { ... }, + async str_replace(command) { ... }, + async insert(command) { ... }, + async delete(command) { ... }, + async rename(command) { ... }, +}; + +const memory = betaMemoryTool(handlers); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [memory], + messages: [{ role: "user", content: "Remember my preferences" }], +}); + +for await (const message of runner) { + console.log(message); +} +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts` + +--- + +## Structured Outputs + +### JSON Outputs (Zod — Recommended) + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { z } from "zod"; +import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; + +const ContactInfoSchema = z.object({ + name: z.string(), + email: z.string(), + plan: z.string(), + interests: z.array(z.string()), + demo_requested: z.boolean(), +}); + +const client = new Anthropic(); + +const response = await client.messages.parse({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.", + }, + ], + output_config: { + format: zodOutputFormat(ContactInfoSchema), + }, +}); + +// parsed_output is null if parsing failed — assert or guard +console.log(response.parsed_output!.name); // "Jane Doe" +``` + +### Strict Tool Use + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Book a flight to Tokyo for 2 passengers on March 15", + }, + ], + tools: [ + { + name: "book_flight", + description: "Book a flight to a destination", + strict: true, + input_schema: { + type: "object", + properties: { + destination: { type: "string" }, + date: { type: "string", format: "date" }, + passengers: { + type: "integer", + enum: [1, 2, 3, 4, 5, 6, 7, 8], + }, + }, + required: ["destination", "date", "passengers"], + additionalProperties: false, + }, + }, + ], +}); +``` diff --git a/junie/versions/2206.4/skills/claude-api/typescript/managed-agents/README.md b/junie/versions/2206.4/skills/claude-api/typescript/managed-agents/README.md new file mode 100644 index 0000000..b4f2a54 --- /dev/null +++ b/junie/versions/2206.4/skills/claude-api/typescript/managed-agents/README.md @@ -0,0 +1,359 @@ +# Managed Agents — TypeScript + +> **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Create an Environment + +```typescript +const environment = await client.beta.environments.create( + { + name: "my-dev-env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, + }, +); +console.log(environment.id); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent: { type: "agent", id: agent.id }`. + +### Minimal + +```typescript +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }], + }, +); + +// 2. Start a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + }, +); +console.log(session.id, session.status); +``` + +### With system prompt and custom tools + +```typescript +const agent = await client.beta.agents.create( + { + name: "Code Reviewer", + model: "claude-opus-4-6", + system: "You are a senior code reviewer.", + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { + type: "custom", + name: "run_tests", + description: "Run the test suite", + input_schema: { + type: "object", + properties: { + test_path: { type: "string", description: "Path to test file" }, + }, + required: ["test_path"], + }, + }, + ], + }, +); + +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + title: "Code review session", + resources: [ + { + type: "github_repository", + url: "https://github.com/owner/repo", + mount_path: "/workspace/repo", + authorization_token: process.env.GITHUB_TOKEN, + branch: "main", + }, + ], + }, +); +``` + +--- + +## Send a User Message + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.message", + content: [{ type: "text", text: "Review the auth module" }], + }, + ], + }, +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```typescript +// Stream-first: open stream and send concurrently +const [events] = await Promise.all([ + collectStream(session.id), + client.beta.sessions.events.send( + session.id, + { events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] }, + ), +]); + +// Standalone stream iteration: +const stream = await client.beta.sessions.stream( + session.id, +); + +for await (const event of stream) { + switch (event.type) { + case "agent.message": + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + break; + case "agent.custom_tool_use": + // Custom tool invocation — session is now idle + console.log(`\nCustom tool call: ${event.tool_name}`); + console.log(`Input: ${JSON.stringify(event.input)}`); + break; + case "session.status_idle": + console.log("\n--- Agent idle ---"); + break; + case "session.status_terminated": + console.log("\n--- Session terminated ---"); + break; + } +} +``` + +--- + +## Provide Custom Tool Result + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.custom_tool_result", + custom_tool_use_id: "sevt_abc123", + content: [{ type: "text", text: "All 42 tests passed." }], + }, + ], + }, +); +``` + +--- + +## Poll Events + +```typescript +const events = await client.beta.sessions.events.list( + session.id, +); +for (const event of events.data) { + console.log(`${event.type}: ${event.id}`); +} +``` + +--- + +## Full Streaming Loop with Custom Tools + +```typescript +function runCustomTool(toolName: string, toolInput: unknown): string { + if (toolName === "run_tests") { + // Your tool implementation here + return "All tests passed."; + } + return `Unknown tool: ${toolName}`; +} + +async function runSession(client: Anthropic, sessionId: string) { + while (true) { + const stream = await client.beta.sessions.stream( + sessionId, + ); + + const toolCalls: Array<{ custom_tool_use_id: string; tool_name: string; input: unknown }> = []; + + for await (const event of stream) { + if (event.type === "agent.message") { + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + } else if (event.type === "agent.custom_tool_use") { + toolCalls.push({ + id: event.id, + tool_name: event.tool_name, + input: event.input, + }); + } else if (event.type === "session.status_idle") { + break; + } else if (event.type === "session.status_terminated") { + return; + } + } + + if (toolCalls.length === 0) break; + + // Process custom tool calls + const results = toolCalls.map((call) => ({ + type: "user.custom_tool_result" as const, + custom_tool_use_id: call.id, + content: [{ type: "text" as const, text: runCustomTool(call.tool_name, call.input) }], + })); + + await client.beta.sessions.events.send( + sessionId, + { events: results }, + ); + } +} +``` + +--- + +## Upload a File + +```typescript +import fs from "fs"; + +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// Use in a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }], + }, +); +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```typescript +import fs from "fs"; + +// List files associated with a session +const files = await client.beta.files.list({ + scope: session.id, +}); +for (const f of files.data) { + console.log(f.filename, f.size_bytes); + + // Download and save to disk + const resp = await client.beta.files.download(f.id); + const buffer = Buffer.from(await resp.arrayBuffer()); + fs.writeFileSync(f.filename, buffer); +} +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty. + +--- + +## Session Management + +```typescript +// Get session details +const session = await client.beta.sessions.retrieve("sess_abc123"); +console.log(session.status, session.usage); + +// List sessions +const sessions = await client.beta.sessions.list(); + +// Delete a session +await client.beta.sessions.delete("sess_abc123"); + +// Archive a session +await client.beta.sessions.archive("sess_abc123"); +``` + +--- + +## MCP Server Integration + +```typescript +// Agent declares MCP server (no auth here — auth goes in a vault) +const agent = await client.beta.agents.create({ + name: "MCP Agent", + model: "claude-opus-4-6", + mcp_servers: [ + { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" }, + ], + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { type: "mcp_toolset", mcp_server_name: "my-tools" }, + ], +}); + +// Session attaches vault(s) containing credentials for those MCP server URLs +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], +}); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2206.4/skills/demo-setup/SKILL.md b/junie/versions/2206.4/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2206.4/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2206.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2206.4/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2206.4/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/BYOK.md b/junie/versions/2206.4/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..7008ef3 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,186 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..fda784a --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,144 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2206.4/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2206.4/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..8cf3e64 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..234cc05 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,75 @@ +# Worktrees + + + + + Slash command to open the worktree menu: /worktree + + +Junie CLI integrates with [Git worktrees](https://git-scm.com/docs/git-worktree) to help you work on multiple +tasks in the same repository without branch conflicts. You can use existing worktrees, create new ones with +predefined names, and switch between them — all without leaving Junie. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own +working tree and index, so you can have different branches checked out simultaneously. Junie CLI makes it easy to +manage worktrees and switch the agent between them. + +## The /worktree command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name + (`-junie-wt-01`, `-02`, and so on) as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, the agent completely resets its state to the new worktree. This makes `/worktree` ideal for +use before starting a new task. + +### Typical workflow + +1. Pre-create a few worktrees so that build caches are ready in each one. +2. When you start a new task, run `/worktree` and switch to one of the prepared worktrees. +3. Prompt Junie to create a branch and rebase to fresh `main`. +4. Work on the task in the worktree while the original directory stays untouched. + +### Transferring uncommitted changes + +If your current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to +transfer them or start clean: + +- **Transfer changes**: Junie uses `git stash` to move uncommitted changes from the source directory to the + target worktree. +- **Start clean**: the worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly (for example, due to conflicts), Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + +## Concurrent session detection + +When a second Junie instance starts on the same project directory, Junie detects the conflict and reminds you +about possible issues with two agents operating on the same files. It then offers to switch to a worktree so +each instance works in its own isolated directory. + +This serves two purposes: + +- **Workspace management**: prevents two agents from making conflicting changes to the same files. +- **Onboarding**: helps you discover worktree support in Junie CLI if you haven't used it before. + +## Auto worktree detection + +If the agent navigates to a worktree directory during a session — whether because you prompted it to or a shell +command changed the working directory — Junie detects the switch and offers to restart with a clean task in the +new worktree. + +Accepting the restart: + +- Prevents the agent from continuing to operate on files in the old worktree. +- Switches the Junie project to the new directory, which affects where Junie looks for the `.junie` folder, + loads skills, reads MCP configurations, and so on. + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory (for example, + `../my-project-junie-wt-01`). Make sure the parent directory is writable. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..df04555 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,138 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..2db6e77 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,450 @@ +# Demo agent + + + +Slash command to invoke the demo agent: /demo + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..1498840 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..4a1ba6f --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,334 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts a new session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Clear up session context + +Use `/new` to clear up the context of the current session and start a new session in Junie CLI interactive mode. +Use `/new ` to start a new session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Resume previous sessions + +To see the session history and resume one of the previous sessions, use `/history`. + +Junie CLI stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2206.4/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2206.4/skills/junie-cli-docs/SKILL.md b/junie/versions/2206.4/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..3f27929 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4001 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts a new session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Clear up session context + +Use `/new` to clear up the context of the current session and start a new session in Junie CLI interactive mode. +Use `/new ` to start a new session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Resume previous sessions + +To see the session history and resume one of the previous sessions, use `/history`. + +Junie CLI stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens a new session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | See the session history and resume one of the previous sessions. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Clear up the context and start a new session. If you provide ``, Junie opens the new session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated git worktree for parallel work. See [Worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Worktrees + +# Worktrees + + + + + Slash command to open the worktree menu: /worktree + + +Junie CLI integrates with [Git worktrees](https://git-scm.com/docs/git-worktree) to help you work on multiple +tasks in the same repository without branch conflicts. You can use existing worktrees, create new ones with +predefined names, and switch between them — all without leaving Junie. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own +working tree and index, so you can have different branches checked out simultaneously. Junie CLI makes it easy to +manage worktrees and switch the agent between them. + +## The /worktree command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name + (`-junie-wt-01`, `-02`, and so on) as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, the agent completely resets its state to the new worktree. This makes `/worktree` ideal for +use before starting a new task. + +### Typical workflow + +1. Pre-create a few worktrees so that build caches are ready in each one. +2. When you start a new task, run `/worktree` and switch to one of the prepared worktrees. +3. Prompt Junie to create a branch and rebase to fresh `main`. +4. Work on the task in the worktree while the original directory stays untouched. + +### Transferring uncommitted changes + +If your current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to +transfer them or start clean: + +- **Transfer changes**: Junie uses `git stash` to move uncommitted changes from the source directory to the + target worktree. +- **Start clean**: the worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly (for example, due to conflicts), Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + +## Concurrent session detection + +When a second Junie instance starts on the same project directory, Junie detects the conflict and reminds you +about possible issues with two agents operating on the same files. It then offers to switch to a worktree so +each instance works in its own isolated directory. + +This serves two purposes: + +- **Workspace management**: prevents two agents from making conflicting changes to the same files. +- **Onboarding**: helps you discover worktree support in Junie CLI if you haven't used it before. + +## Auto worktree detection + +If the agent navigates to a worktree directory during a session — whether because you prompted it to or a shell +command changed the working directory — Junie detects the switch and offers to restart with a clean task in the +new worktree. + +Accepting the restart: + +- Prevents the agent from continuing to operate on files in the old worktree. +- Switches the Junie project to the new directory, which affects where Junie looks for the `.junie` folder, + loads skills, reads MCP configurations, and so on. + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory (for example, + `../my-project-junie-wt-01`). Make sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + +Slash command to invoke the demo agent: /demo + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2206.4/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2206.4/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..77483e4 --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens a new session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | See the session history and resume one of the previous sessions. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Clear up the context and start a new session. If you provide ``, Junie opens the new session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated git worktree for parallel work. See [Worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + + diff --git a/junie/versions/2206.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2206.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..7a888ac --- /dev/null +++ b/junie/versions/2206.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,157 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2285.4/skills/claude-api/LICENSE.txt b/junie/versions/2285.4/skills/claude-api/LICENSE.txt new file mode 100644 index 0000000..7a4a3ea --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/LICENSE.txt @@ -0,0 +1,202 @@ + + Apache License + Version 2.0, January 2004 + http://www.apache.org/licenses/ + + TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION + + 1. Definitions. + + "License" shall mean the terms and conditions for use, reproduction, + and distribution as defined by Sections 1 through 9 of this document. + + "Licensor" shall mean the copyright owner or entity authorized by + the copyright owner that is granting the License. + + "Legal Entity" shall mean the union of the acting entity and all + other entities that control, are controlled by, or are under common + control with that entity. For the purposes of this definition, + "control" means (i) the power, direct or indirect, to cause the + direction or management of such entity, whether by contract or + otherwise, or (ii) ownership of fifty percent (50%) or more of the + outstanding shares, or (iii) beneficial ownership of such entity. + + "You" (or "Your") shall mean an individual or Legal Entity + exercising permissions granted by this License. + + "Source" form shall mean the preferred form for making modifications, + including but not limited to software source code, documentation + source, and configuration files. + + "Object" form shall mean any form resulting from mechanical + transformation or translation of a Source form, including but + not limited to compiled object code, generated documentation, + and conversions to other media types. + + "Work" shall mean the work of authorship, whether in Source or + Object form, made available under the License, as indicated by a + copyright notice that is included in or attached to the work + (an example is provided in the Appendix below). + + "Derivative Works" shall mean any work, whether in Source or Object + form, that is based on (or derived from) the Work and for which the + editorial revisions, annotations, elaborations, or other modifications + represent, as a whole, an original work of authorship. For the purposes + of this License, Derivative Works shall not include works that remain + separable from, or merely link (or bind by name) to the interfaces of, + the Work and Derivative Works thereof. + + "Contribution" shall mean any work of authorship, including + the original version of the Work and any modifications or additions + to that Work or Derivative Works thereof, that is intentionally + submitted to Licensor for inclusion in the Work by the copyright owner + or by an individual or Legal Entity authorized to submit on behalf of + the copyright owner. For the purposes of this definition, "submitted" + means any form of electronic, verbal, or written communication sent + to the Licensor or its representatives, including but not limited to + communication on electronic mailing lists, source code control systems, + and issue tracking systems that are managed by, or on behalf of, the + Licensor for the purpose of discussing and improving the Work, but + excluding communication that is conspicuously marked or otherwise + designated in writing by the copyright owner as "Not a Contribution." + + "Contributor" shall mean Licensor and any individual or Legal Entity + on behalf of whom a Contribution has been received by Licensor and + subsequently incorporated within the Work. + + 2. Grant of Copyright License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + copyright license to reproduce, prepare Derivative Works of, + publicly display, publicly perform, sublicense, and distribute the + Work and such Derivative Works in Source or Object form. + + 3. Grant of Patent License. Subject to the terms and conditions of + this License, each Contributor hereby grants to You a perpetual, + worldwide, non-exclusive, no-charge, royalty-free, irrevocable + (except as stated in this section) patent license to make, have made, + use, offer to sell, sell, import, and otherwise transfer the Work, + where such license applies only to those patent claims licensable + by such Contributor that are necessarily infringed by their + Contribution(s) alone or by combination of their Contribution(s) + with the Work to which such Contribution(s) was submitted. If You + institute patent litigation against any entity (including a + cross-claim or counterclaim in a lawsuit) alleging that the Work + or a Contribution incorporated within the Work constitutes direct + or contributory patent infringement, then any patent licenses + granted to You under this License for that Work shall terminate + as of the date such litigation is filed. + + 4. Redistribution. You may reproduce and distribute copies of the + Work or Derivative Works thereof in any medium, with or without + modifications, and in Source or Object form, provided that You + meet the following conditions: + + (a) You must give any other recipients of the Work or + Derivative Works a copy of this License; and + + (b) You must cause any modified files to carry prominent notices + stating that You changed the files; and + + (c) You must retain, in the Source form of any Derivative Works + that You distribute, all copyright, patent, trademark, and + attribution notices from the Source form of the Work, + excluding those notices that do not pertain to any part of + the Derivative Works; and + + (d) If the Work includes a "NOTICE" text file as part of its + distribution, then any Derivative Works that You distribute must + include a readable copy of the attribution notices contained + within such NOTICE file, excluding those notices that do not + pertain to any part of the Derivative Works, in at least one + of the following places: within a NOTICE text file distributed + as part of the Derivative Works; within the Source form or + documentation, if provided along with the Derivative Works; or, + within a display generated by the Derivative Works, if and + wherever such third-party notices normally appear. The contents + of the NOTICE file are for informational purposes only and + do not modify the License. You may add Your own attribution + notices within Derivative Works that You distribute, alongside + or as an addendum to the NOTICE text from the Work, provided + that such additional attribution notices cannot be construed + as modifying the License. + + You may add Your own copyright statement to Your modifications and + may provide additional or different license terms and conditions + for use, reproduction, or distribution of Your modifications, or + for any such Derivative Works as a whole, provided Your use, + reproduction, and distribution of the Work otherwise complies with + the conditions stated in this License. + + 5. Submission of Contributions. Unless You explicitly state otherwise, + any Contribution intentionally submitted for inclusion in the Work + by You to the Licensor shall be under the terms and conditions of + this License, without any additional terms or conditions. + Notwithstanding the above, nothing herein shall supersede or modify + the terms of any separate license agreement you may have executed + with Licensor regarding such Contributions. + + 6. Trademarks. This License does not grant permission to use the trade + names, trademarks, service marks, or product names of the Licensor, + except as required for reasonable and customary use in describing the + origin of the Work and reproducing the content of the NOTICE file. + + 7. Disclaimer of Warranty. Unless required by applicable law or + agreed to in writing, Licensor provides the Work (and each + Contributor provides its Contributions) on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or + implied, including, without limitation, any warranties or conditions + of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A + PARTICULAR PURPOSE. You are solely responsible for determining the + appropriateness of using or redistributing the Work and assume any + risks associated with Your exercise of permissions under this License. + + 8. Limitation of Liability. In no event and under no legal theory, + whether in tort (including negligence), contract, or otherwise, + unless required by applicable law (such as deliberate and grossly + negligent acts) or agreed to in writing, shall any Contributor be + liable to You for damages, including any direct, indirect, special, + incidental, or consequential damages of any character arising as a + result of this License or out of the use or inability to use the + Work (including but not limited to damages for loss of goodwill, + work stoppage, computer failure or malfunction, or any and all + other commercial damages or losses), even if such Contributor + has been advised of the possibility of such damages. + + 9. Accepting Warranty or Additional Liability. While redistributing + the Work or Derivative Works thereof, You may choose to offer, + and charge a fee for, acceptance of support, warranty, indemnity, + or other liability obligations and/or rights consistent with this + License. However, in accepting such obligations, You may act only + on Your own behalf and on Your sole responsibility, not on behalf + of any other Contributor, and only if You agree to indemnify, + defend, and hold each Contributor harmless for any liability + incurred by, or claims asserted against, such Contributor by reason + of your accepting any such warranty or additional liability. + + END OF TERMS AND CONDITIONS + + APPENDIX: How to apply the Apache License to your work. + + To apply the Apache License to your work, attach the following + boilerplate notice, with the fields enclosed by brackets "[]" + replaced with your own identifying information. (Don't include + the brackets!) The text should be enclosed in the appropriate + comment syntax for the file format. We also recommend that a + file or class name and description of purpose be included on the + same "printed page" as the copyright notice for easier + identification within third-party archives. + + Copyright [yyyy] [name of copyright owner] + + Licensed under the Apache License, Version 2.0 (the "License"); + you may not use this file except in compliance with the License. + You may obtain a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + + Unless required by applicable law or agreed to in writing, software + distributed under the License is distributed on an "AS IS" BASIS, + WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + See the License for the specific language governing permissions and + limitations under the License. \ No newline at end of file diff --git a/junie/versions/2285.4/skills/claude-api/SKILL.md b/junie/versions/2285.4/skills/claude-api/SKILL.md new file mode 100644 index 0000000..1431d44 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/SKILL.md @@ -0,0 +1,317 @@ +--- +name: claude-api +description: "Build, debug, and optimize Claude API / Anthropic SDK apps. Apps built with this skill should include prompt caching. TRIGGER when: code imports anthropic/@anthropic-ai/sdk; user asks to use the Claude API, Anthropic SDKs, or Managed Agents (/v1/agents, /v1/sessions, /v1/environments). DO NOT TRIGGER when: code imports `openai`/other AI SDK, general programming, or ML/data-science tasks." +license: Complete terms in LICENSE.txt +--- + + +# Building LLM-Powered Applications with Claude + +This skill helps you build LLM-powered applications with Claude. Choose the right surface based on your needs, detect the project language, then read the relevant language-specific documentation. + +## Before You Start + +Scan the target file (or, if no target file, the prompt and project) for non-Anthropic provider markers — `import openai`, `from openai`, `langchain_openai`, `OpenAI(`, `gpt-4`, `gpt-5`, file names like `agent-openai.py` or `*-generic.py`, or any explicit instruction to keep the code provider-neutral. If you find any, stop and tell the user that this skill produces Claude/Anthropic SDK code; ask whether they want to switch the file to Claude or want a non-Claude implementation. Do not edit a non-Anthropic file with Anthropic SDK calls. + +## Output Requirement + +When the user asks you to add, modify, or implement a Claude feature, your code must call Claude through one of: + +1. **The official Anthropic SDK** for the project's language (`anthropic`, `@anthropic-ai/sdk`, `com.anthropic.*`, etc.). This is the default whenever a supported SDK exists for the project. +2. **Raw HTTP** (`curl`, `requests`, `fetch`, `httpx`, etc.) — only when the user explicitly asks for cURL/REST/raw HTTP, the project is a shell/cURL project, or the language has no official SDK. + +Never mix the two — don't reach for `requests`/`fetch` in a Python or TypeScript project just because it feels lighter. Never fall back to OpenAI-compatible shims. + +**Never guess SDK usage.** Function names, class names, namespaces, method signatures, and import paths must come from explicit documentation — either the `{lang}/` files in this skill or the official SDK repositories or documentation links listed in `shared/live-sources.md`. If the binding you need is not explicitly documented in the skill files, WebFetch the relevant SDK repo from `shared/live-sources.md` before writing code. Do not infer Ruby/Java/Go/PHP/C# APIs from cURL shapes or from another language's SDK. + +## Defaults + +Unless the user requests otherwise: + +For the Claude model version, please use Claude Opus 4.6, which you can access via the exact model string `claude-opus-4-6`. Please default to using adaptive thinking (`thinking: {type: "adaptive"}`) for anything remotely complicated. And finally, please default to streaming for any request that may involve long input, long output, or high `max_tokens` — it prevents hitting request timeouts. Use the SDK's `.get_final_message()` / `.finalMessage()` helper to get the complete response if you don't need to handle individual stream events + +--- + +## Subcommands + +If the User Request at the bottom of this prompt is a bare subcommand string (no prose), search every **Subcommands** table in this document — including any in sections appended below — and follow the matching Action column directly. This lets users invoke specific flows via `/claude-api `. If no table in the document matches, treat the request as normal prose. + + + +--- + +## Language Detection + +Before reading code examples, determine which language the user is working in: + +1. **Look at project files** to infer the language: + + - `*.py`, `requirements.txt`, `pyproject.toml`, `setup.py`, `Pipfile` → **Python** — read from `python/` + - `*.ts`, `*.tsx`, `package.json`, `tsconfig.json` → **TypeScript** — read from `typescript/` + - `*.js`, `*.jsx` (no `.ts` files present) → **TypeScript** — JS uses the same SDK, read from `typescript/` + - `*.java`, `pom.xml`, `build.gradle` → **Java** — read from `java/` + - `*.kt`, `*.kts`, `build.gradle.kts` → **Java** — Kotlin uses the Java SDK, read from `java/` + - `*.scala`, `build.sbt` → **Java** — Scala uses the Java SDK, read from `java/` + - `*.go`, `go.mod` → **Go** — read from `go/` + - `*.rb`, `Gemfile` → **Ruby** — read from `ruby/` + - `*.cs`, `*.csproj` → **C#** — read from `csharp/` + - `*.php`, `composer.json` → **PHP** — read from `php/` + +2. **If multiple languages detected** (e.g., both Python and TypeScript files): + + - Check which language the user's current file or question relates to + - If still ambiguous, ask: "I detected both Python and TypeScript files. Which language are you using for the Claude API integration?" + +3. **If language can't be inferred** (empty project, no source files, or unsupported language): + + - Use AskUserQuestion with options: Python, TypeScript, Java, Go, Ruby, cURL/raw HTTP, C#, PHP + - If AskUserQuestion is unavailable, default to Python examples and note: "Showing Python examples. Let me know if you need a different language." + +4. **If unsupported language detected** (Rust, Swift, C++, Elixir, etc.): + + - Suggest cURL/raw HTTP examples from `curl/` and note that community SDKs may exist + - Offer to show Python or TypeScript examples as reference implementations + +5. **If user needs cURL/raw HTTP examples**, read from `curl/`. + +### Language-Specific Feature Support + +| Language | Tool Runner | Managed Agents | Notes | +| ---------- | ----------- | -------------- | ------------------------------------- | +| Python | Yes (beta) | Yes (beta) | Full support — `@beta_tool` decorator | +| TypeScript | Yes (beta) | Yes (beta) | Full support — `betaZodTool` + Zod | +| Java | Yes (beta) | Yes (beta) | Beta tool use with annotated classes | +| Go | Yes (beta) | Yes (beta) | `BetaToolRunner` in `toolrunner` pkg | +| Ruby | Yes (beta) | Yes (beta) | `BaseTool` + `tool_runner` in beta | +| C# | No | No | Official SDK | +| PHP | Yes (beta) | Yes (beta) | `BetaRunnableTool` + `toolRunner()` | +| cURL | N/A | Yes (beta) | Raw HTTP, no SDK features | + +> **Managed Agents code examples**: dedicated language-specific READMEs are provided for Python, TypeScript, Go, Ruby, PHP, Java, and cURL (`{lang}/managed-agents/README.md`, `curl/managed-agents.md`). Read your language's README plus the language-agnostic `shared/managed-agents-*.md` concept files. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. If a binding you need isn't shown in the README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use cURL-style raw HTTP requests against the API. + +--- + +## Which Surface Should I Use? + +> **Start simple.** Default to the simplest tier that meets your needs. Single API calls and workflows handle most use cases — only reach for agents when the task genuinely requires open-ended, model-driven exploration. + +| Use Case | Tier | Recommended Surface | Why | +| ----------------------------------------------- | --------------- | ------------------------- | ------------------------------------------------------------ | +| Classification, summarization, extraction, Q&A | Single LLM call | **Claude API** | One request, one response | +| Batch processing or embeddings | Single LLM call | **Claude API** | Specialized endpoints | +| Multi-step pipelines with code-controlled logic | Workflow | **Claude API + tool use** | You orchestrate the loop | +| Custom agent with your own tools | Agent | **Claude API + tool use** | Maximum flexibility | +| Server-managed stateful agent with workspace | Agent | **Managed Agents** | Anthropic runs the loop and hosts the tool-execution sandbox | +| Persisted, versioned agent configs | Agent | **Managed Agents** | Agents are stored objects; sessions pin to a version | +| Long-running multi-turn agent with file mounts | Agent | **Managed Agents** | Per-session containers, SSE event stream, Skills + MCP | + +> **Note:** Managed Agents is the right choice when you want Anthropic to run the agent loop *and* host the container where tools execute — file ops, bash, code execution all run in the per-session workspace. If you want to host the compute yourself or run your own custom tool runtime, Claude API + tool use is the right choice — use the tool runner for automatic loop handling, or the manual loop for fine-grained control (approval gates, custom logging, conditional execution). + +> **Third-party providers (Amazon Bedrock, Google Vertex AI, Microsoft Foundry):** Managed Agents is **not available** on Bedrock, Vertex, or Foundry. If you are deploying through any third-party provider, use **Claude API + tool use** for all use cases — including ones where Managed Agents would otherwise be the recommended surface. + +### Decision Tree + +``` +What does your application need? + +0. Are you deploying through Amazon Bedrock, Google Vertex AI, or Microsoft Foundry? + └── Yes → Claude API (+ tool use for agents) — Managed Agents is 1P only. + No → continue. + +1. Single LLM call (classification, summarization, extraction, Q&A) + └── Claude API — one request, one response + +2. Do you want Anthropic to run the agent loop and host a per-session + container where Claude executes tools (bash, file ops, code)? + └── Yes → Managed Agents — server-managed sessions, persisted agent configs, + SSE event stream, Skills + MCP, file mounts. + Examples: "stateful coding agent with a workspace per task", + "long-running research agent that streams events to a UI", + "agent with persisted, versioned config used across many sessions" + +3. Workflow (multi-step, code-orchestrated, with your own tools) + └── Claude API with tool use — you control the loop + +4. Open-ended agent (model decides its own trajectory, your own tools, you host the compute) + └── Claude API agentic loop (maximum flexibility) +``` + +### Should I Build an Agent? + +Before choosing the agent tier, check all four criteria: + +- **Complexity** — Is the task multi-step and hard to fully specify in advance? (e.g., "turn this design doc into a PR" vs. "extract the title from this PDF") +- **Value** — Does the outcome justify higher cost and latency? +- **Viability** — Is Claude capable at this task type? +- **Cost of error** — Can errors be caught and recovered from? (tests, review, rollback) + +If the answer is "no" to any of these, stay at a simpler tier (single call or workflow). + +--- + +## Architecture + +Everything goes through `POST /v1/messages`. Tools and output constraints are features of this single endpoint — not separate APIs. + +**User-defined tools** — You define tools (via decorators, Zod schemas, or raw JSON), and the SDK's tool runner handles calling the API, executing your functions, and looping until Claude is done. For full control, you can write the loop manually. + +**Server-side tools** — Anthropic-hosted tools that run on Anthropic's infrastructure. Code execution is fully server-side (declare it in `tools`, Claude runs code automatically). Computer use can be server-hosted or self-hosted. + +**Structured outputs** — Constrains the Messages API response format (`output_config.format`) and/or tool parameter validation (`strict: true`). The recommended approach is `client.messages.parse()` which validates responses against your schema automatically. Note: the old `output_format` parameter is deprecated; use `output_config: {format: {...}}` on `messages.create()`. + +**Supporting endpoints** — Batches (`POST /v1/messages/batches`), Files (`POST /v1/files`), Token Counting, and Models (`GET /v1/models`, `GET /v1/models/{id}` — live capability/context-window discovery) feed into or support Messages API requests. + +--- + +## Current Models (cached: 2026-02-17) + +| Model | Model ID | Context | Input $/1M | Output $/1M | +| ----------------- | ------------------- | -------------- | ---------- | ----------- | +| Claude Opus 4.6 | `claude-opus-4-6` | 200K (1M beta) | $5.00 | $25.00 | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | 200K (1M beta) | $3.00 | $15.00 | +| Claude Haiku 4.5 | `claude-haiku-4-5` | 200K | $1.00 | $5.00 | + +**ALWAYS use `claude-opus-4-6` unless the user explicitly names a different model.** This is non-negotiable. Do not use `claude-sonnet-4-6`, `claude-sonnet-4-5`, or any other model unless the user literally says "use sonnet" or "use haiku". Never downgrade for cost — that's the user's decision, not yours. + +**CRITICAL: Use only the exact model ID strings from the table above — they are complete as-is. Do not append date suffixes.** For example, use `claude-sonnet-4-5`, never `claude-sonnet-4-5-20250514` or any other date-suffixed variant you might recall from training data. If the user requests an older model not in the table (e.g., "opus 4.5", "sonnet 3.7"), read `shared/models.md` for the exact ID — do not construct one yourself. + +A note: if any of the model strings above look unfamiliar to you, that's to be expected — that just means they were released after your training data cutoff. Rest assured they are real models; we wouldn't mess with you like that. + +**Live capability lookup:** The table above is cached. When the user asks "what's the context window for X", "does X support vision/thinking/effort", or "which models support Y", query the Models API (`client.models.retrieve(id)` / `client.models.list()`) — see `shared/models.md` for the field reference and capability-filter examples. + +--- + +## Thinking & Effort (Quick Reference) + +**Opus 4.6 — Adaptive thinking (recommended):** Use `thinking: {type: "adaptive"}`. Claude dynamically decides when and how much to think. No `budget_tokens` needed — `budget_tokens` is deprecated on Opus 4.6 and Sonnet 4.6 and must not be used. Adaptive thinking also automatically enables interleaved thinking (no beta header needed). **When the user asks for "extended thinking", a "thinking budget", or `budget_tokens`: always use Opus 4.6 with `thinking: {type: "adaptive"}`. The concept of a fixed token budget for thinking is deprecated — adaptive thinking replaces it. Do NOT use `budget_tokens` and do NOT switch to an older model.** + +**Effort parameter (GA, no beta header):** Controls thinking depth and overall token spend via `output_config: {effort: "low"|"medium"|"high"|"max"}` (inside `output_config`, not top-level). Default is `high` (equivalent to omitting it). `max` is Opus 4.6 only. Works on Opus 4.5, Opus 4.6, and Sonnet 4.6. Will error on Sonnet 4.5 / Haiku 4.5. Combine with adaptive thinking for the best cost-quality tradeoffs. Lower effort means fewer and more-consolidated tool calls, less preamble, and terser confirmations — `medium` is often a favorable balance; use `max` when correctness matters more than cost; use `low` for subagents or simple tasks. + +**Sonnet 4.6:** Supports adaptive thinking (`thinking: {type: "adaptive"}`). `budget_tokens` is deprecated on Sonnet 4.6 — use adaptive thinking instead. + +**Older models (only if explicitly requested):** If the user specifically asks for Sonnet 4.5 or another older model, use `thinking: {type: "enabled", budget_tokens: N}`. `budget_tokens` must be less than `max_tokens` (minimum 1024). Never choose an older model just because the user mentions `budget_tokens` — use Opus 4.6 with adaptive thinking instead. + +--- + +## Compaction (Quick Reference) + +**Beta, Opus 4.6 and Sonnet 4.6.** For long-running conversations that may exceed the 200K context window, enable server-side compaction. The API automatically summarizes earlier context when it approaches the trigger threshold (default: 150K tokens). Requires beta header `compact-2026-01-12`. + +**Critical:** Append `response.content` (not just the text) back to your messages on every turn. Compaction blocks in the response must be preserved — the API uses them to replace the compacted history on the next request. Extracting only the text string and appending that will silently lose the compaction state. + +See `{lang}/claude-api/README.md` (Compaction section) for code examples. Full docs via WebFetch in `shared/live-sources.md`. + +--- + +## Prompt Caching (Quick Reference) + +**Prefix match.** Any byte change anywhere in the prefix invalidates everything after it. Render order is `tools` → `system` → `messages`. Keep stable content first (frozen system prompt, deterministic tool list), put volatile content (timestamps, per-request IDs, varying questions) after the last `cache_control` breakpoint. + +**Top-level auto-caching** (`cache_control: {type: "ephemeral"}` on `messages.create()`) is the simplest option when you don't need fine-grained placement. Max 4 breakpoints per request. Minimum cacheable prefix is ~1024 tokens — shorter prefixes silently won't cache. + +**Verify with `usage.cache_read_input_tokens`** — if it's zero across repeated requests, a silent invalidator is at work (`datetime.now()` in system prompt, unsorted JSON, varying tool set). + +For placement patterns, architectural guidance, and the silent-invalidator audit checklist: read `shared/prompt-caching.md`. Language-specific syntax: `{lang}/claude-api/README.md` (Prompt Caching section). + +--- + +## Managed Agents (Beta) + +**Managed Agents** is a third surface: server-managed stateful agents with Anthropic-hosted tool execution. You create a persisted, versioned Agent config (`POST /v1/agents`), then start Sessions that reference it. Each session provisions a container as the agent's workspace — bash, file ops, and code execution run there; the agent loop itself runs on Anthropic's orchestration layer and acts on the container via tools. The session streams events; you send messages and tool results back. + +**Managed Agents is first-party only.** It is not available on Amazon Bedrock, Google Vertex AI, or Microsoft Foundry. For agents on third-party providers, use Claude API + tool use. + +**Mandatory flow:** Agent (once) → Session (every run). `model`/`system`/`tools` live on the agent, never the session. See `shared/managed-agents-overview.md` for the full reading guide, beta headers, and pitfalls. + +**Beta headers:** `managed-agents-2026-04-01` — the SDK sets this automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills API uses `skills-2025-10-02` and Files API uses `files-api-2025-04-14`, but you don't need to explicitly pass those in for endpoints other than `/v1/skills` and `/v1/files`. + +**Subcommands** — invoke directly with `/claude-api `: + +| Subcommand | Action | +|---|---| +| `managed-agents-onboard` | Walk the user through setting up a Managed Agent from scratch. **Read `shared/managed-agents-onboarding.md` immediately** and follow its interview script: mental model → know-or-explore branch → template config → session setup → emit code. Do not summarize — run the interview. | + +**Reading guide:** Start with `shared/managed-agents-overview.md`, then the topical `shared/managed-agents-*.md` files (core, environments, tools, events, client-patterns, onboarding, api-reference). For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently have Managed Agents support; use raw HTTP from `curl/managed-agents.md` as a reference. + +**When the user wants to set up a Managed Agent from scratch** (e.g. "how do I get started", "walk me through creating one", "set up a new agent"): read `shared/managed-agents-onboarding.md` and run its interview — same flow as the `managed-agents-onboard` subcommand. + +**When the user asks "how do I write the client code for X":** reach for `shared/managed-agents-client-patterns.md` — covers lossless stream reconnect, `processed_at` queued/processed gate, interrupt, `tool_confirmation` round-trip, the correct idle/terminated break gate, post-idle status race, stream-first ordering, file-mount gotchas, keeping credentials host-side via custom tools, etc. + +--- + +## Reading Guide + +After detecting the language, read the relevant files based on what the user needs: + +### Quick Task Reference + +**Single text classification/summarization/extraction/Q&A:** +→ Read only `{lang}/claude-api/README.md` + +**Chat UI or real-time response display:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/streaming.md` + +**Long-running conversations (may exceed context window):** +→ Read `{lang}/claude-api/README.md` — see Compaction section + +**Prompt caching / optimize caching / "why is my cache hit rate low":** +→ Read `shared/prompt-caching.md` + `{lang}/claude-api/README.md` (Prompt Caching section) + +**Function calling / tool use / agents:** +→ Read `{lang}/claude-api/README.md` + `shared/tool-use-concepts.md` + `{lang}/claude-api/tool-use.md` + +**Agent design (tool surface, context management, caching strategy):** +→ Read `shared/agent-design.md` + +**Batch processing (non-latency-sensitive):** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/batches.md` + +**File uploads across multiple requests:** +→ Read `{lang}/claude-api/README.md` + `{lang}/claude-api/files-api.md` + +**Managed Agents (server-managed stateful agents with workspace):** +→ Read `shared/managed-agents-overview.md` + the rest of the `shared/managed-agents-*.md` files. For Python, TypeScript, Go, Ruby, PHP, and Java, read `{lang}/managed-agents/README.md` for code examples. For cURL, read `curl/managed-agents.md`. **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML (URL in `shared/live-sources.md`). If a binding you need isn't shown in the language README, WebFetch the relevant entry from `shared/live-sources.md` rather than guess. C# does not currently support Managed Agents — use raw HTTP from `curl/managed-agents.md` as a reference. + +### Claude API (Full File Reference) + +Read the **language-specific Claude API folder** (`{language}/claude-api/`): + +1. **`{language}/claude-api/README.md`** — **Read this first.** Installation, quick start, common patterns, error handling. +2. **`shared/tool-use-concepts.md`** — Read when the user needs function calling, code execution, memory, or structured outputs. Covers conceptual foundations. +3. **`shared/agent-design.md`** — Read when designing an agent: bash vs. dedicated tools, programmatic tool calling, tool search/skills, context editing vs. compaction vs. memory, caching principles. +4. **`{language}/claude-api/tool-use.md`** — Read for language-specific tool use code examples (tool runner, manual loop, code execution, memory, structured outputs). +5. **`{language}/claude-api/streaming.md`** — Read when building chat UIs or interfaces that display responses incrementally. +6. **`{language}/claude-api/batches.md`** — Read when processing many requests offline (not latency-sensitive). Runs asynchronously at 50% cost. +7. **`{language}/claude-api/files-api.md`** — Read when sending the same file across multiple requests without re-uploading. +8. **`shared/prompt-caching.md`** — Read when adding or optimizing prompt caching. Covers prefix-stability design, breakpoint placement, and anti-patterns that silently invalidate cache. +9. **`shared/error-codes.md`** — Read when debugging HTTP errors or implementing error handling. +10. **`shared/live-sources.md`** — WebFetch URLs for fetching the latest official documentation. + +> **Note:** For Java, Go, Ruby, C#, PHP, and cURL — these have a single file each covering all basics. Read that file plus `shared/tool-use-concepts.md` and `shared/error-codes.md` as needed. + +> **Note:** For the Managed Agents file reference, see the `## Managed Agents (Beta)` section above — it lists every `shared/managed-agents-*.md` file and the language-specific READMEs. + +--- + +## When to Use WebFetch + +Use WebFetch to get the latest documentation when: + +- User asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered here + +Live documentation URLs are in `shared/live-sources.md`. + +## Common Pitfalls + +- Don't truncate inputs when passing files or content to the API. If the content is too long to fit in the context window, notify the user and discuss options (chunking, summarization, etc.) rather than silently truncating. +- **Opus 4.6 / Sonnet 4.6 thinking:** Use `thinking: {type: "adaptive"}` — do NOT use `budget_tokens` (deprecated on both Opus 4.6 and Sonnet 4.6). For older models, `budget_tokens` must be less than `max_tokens` (minimum 1024). This will throw an error if you get it wrong. +- **Opus 4.6 prefill removed:** Assistant message prefills (last-assistant-turn prefills) return a 400 error on Opus 4.6. Use structured outputs (`output_config.format`) or system prompt instructions to control response format instead. +- **`max_tokens` defaults:** Don't lowball `max_tokens` — hitting the cap truncates output mid-thought and requires a retry. For non-streaming requests, default to `~16000` (keeps responses under SDK HTTP timeouts). For streaming requests, default to `~64000` (timeouts aren't a concern, so give the model room). Only go lower when you have a hard reason: classification (`~256`), cost caps, or deliberately short outputs. +- **128K output tokens:** Opus 4.6 supports up to 128K `max_tokens`, but the SDKs require streaming for values that large to avoid HTTP timeouts. Use `.stream()` with `.get_final_message()` / `.finalMessage()`. +- **Tool call JSON parsing (Opus 4.6):** Opus 4.6 may produce different JSON string escaping in tool call `input` fields (e.g., Unicode or forward-slash escaping). Always parse tool inputs with `json.loads()` / `JSON.parse()` — never do raw string matching on the serialized input. +- **Structured outputs (all models):** Use `output_config: {format: {...}}` instead of the deprecated `output_format` parameter on `messages.create()`. This is a general API change, not 4.6-specific. +- **Don't reimplement SDK functionality:** The SDK provides high-level helpers — use them instead of building from scratch. Specifically: use `stream.finalMessage()` instead of wrapping `.on()` events in `new Promise()`; use typed exception classes (`Anthropic.RateLimitError`, etc.) instead of string-matching error messages; use SDK types (`Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.Message`, etc.) instead of redefining equivalent interfaces. +- **Don't define custom types for SDK data structures:** The SDK exports types for all API objects. Use `Anthropic.MessageParam` for messages, `Anthropic.Tool` for tool definitions, `Anthropic.ToolUseBlock` / `Anthropic.ToolResultBlockParam` for tool results, `Anthropic.Message` for responses. Defining your own `interface ChatMessage { role: string; content: unknown }` duplicates what the SDK already provides and loses type safety. +- **Report and document output:** For tasks that produce reports, documents, or visualizations, the code execution sandbox has `python-docx`, `python-pptx`, `matplotlib`, `pillow`, and `pypdf` pre-installed. Claude can generate formatted files (DOCX, PDF, charts) and return them via the Files API — consider this for "report" or "document" type requests instead of plain stdout text. diff --git a/junie/versions/2285.4/skills/claude-api/csharp/claude-api.md b/junie/versions/2285.4/skills/claude-api/csharp/claude-api.md new file mode 100644 index 0000000..e0e790a --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/csharp/claude-api.md @@ -0,0 +1,402 @@ +# Claude API — C# + +> **Note:** The C# SDK is the official Anthropic SDK for C#. Tool use is supported via the Messages API. A class-annotation-based tool runner is not available; use raw tool definitions with JSON schema. The SDK also supports Microsoft.Extensions.AI IChatClient integration with function invocation. + +## Installation + +```bash +dotnet add package Anthropic +``` + +## Client Initialization + +```csharp +using Anthropic; + +// Default (uses ANTHROPIC_API_KEY env var) +AnthropicClient client = new(); + +// Explicit API key (use environment variables — never hardcode keys) +AnthropicClient client = new() { + ApiKey = Environment.GetEnvironmentVariable("ANTHROPIC_API_KEY") +}; +``` + +--- + +## Basic Message Request + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Messages = [new() { Role = Role.User, Content = "What is the capital of France?" }] +}; +var response = await client.Messages.Create(parameters); + +// ContentBlock is a union wrapper. .Value unwraps to the variant object, +// then OfType filters to the type you want. Or use the TryPick* idiom +// shown in the Thinking section below. +foreach (var text in response.Content.Select(b => b.Value).OfType()) +{ + Console.WriteLine(text.Text); +} +``` + +--- + +## Streaming + +```csharp +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 64000, + Messages = [new() { Role = Role.User, Content = "Write a haiku" }] +}; + +await foreach (RawMessageStreamEvent streamEvent in client.Messages.CreateStreaming(parameters)) +{ + if (streamEvent.TryPickContentBlockDelta(out var delta) && + delta.Delta.TryPickText(out var text)) + { + Console.Write(text.Text); + } +} +``` + +**`RawMessageStreamEvent` TryPick methods** (naming drops the `Message`/`Raw` prefix): `TryPickStart`, `TryPickDelta`, `TryPickStop`, `TryPickContentBlockStart`, `TryPickContentBlockDelta`, `TryPickContentBlockStop`. There is no `TryPickMessageStop` — use `TryPickStop`. + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```csharp +using Anthropic.Models.Messages; + +var response = await client.Messages.Create(new MessageCreateParams +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + // ThinkingConfigParam? implicitly converts from the concrete variant classes — + // no wrapper needed. + Thinking = new ThinkingConfigAdaptive(), + Messages = + [ + new() { Role = Role.User, Content = "Solve: 27 * 453" }, + ], +}); + +// ThinkingBlock(s) precede TextBlock in Content. TryPick* narrows the union. +foreach (var block in response.Content) +{ + if (block.TryPickThinking(out ThinkingBlock? t)) + { + Console.WriteLine($"[thinking] {t.Thinking}"); + } + else if (block.TryPickText(out TextBlock? text)) + { + Console.WriteLine(text.Text); + } +} +``` + +> **Deprecated:** `new ThinkingConfigEnabled { BudgetTokens = N }` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +Alternative to `TryPick*`: `.Select(b => b.Value).OfType()` (same LINQ pattern as the Basic Message example). + +--- + +## Tool Use + +### Defining a tool + +`Tool` (NOT `ToolParam`) with an `InputSchema` record. `InputSchema.Type` is auto-set to `"object"` by the constructor — don't set it. `ToolUnion` has an implicit conversion from `Tool`, triggered by the collection expression `[...]`. + +```csharp +using System.Text.Json; +using Anthropic.Models.Messages; + +var parameters = new MessageCreateParams +{ + Model = Model.ClaudeSonnet4_6, + MaxTokens = 16000, + Tools = [ + new Tool { + Name = "get_weather", + Description = "Get the current weather in a given location", + InputSchema = new() { + Properties = new Dictionary { + ["location"] = JsonSerializer.SerializeToElement( + new { type = "string", description = "City name" }), + }, + Required = ["location"], + }, + }, + ], + Messages = [new() { Role = Role.User, Content = "Weather in Paris?" }], +}; +``` + +Derived from `anthropic-sdk-csharp/src/Anthropic/Models/Messages/Tool.cs` and `ToolUnion.cs:799` (implicit conversion). + +See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. +### Converting response content to the follow-up assistant message + +When echoing Claude's response back in the assistant turn, **there is no `.ToParam()` helper** — manually reconstruct each `ContentBlock` variant as its `*Param` counterpart. Do NOT use `new ContentBlockParam(block.Json)`: it compiles and serializes, but `.Value` stays `null` so `TryPick*`/`Validate()` fail (degraded JSON pass-through, not the typed path). + +```csharp +using Anthropic.Models.Messages; + +Message response = await client.Messages.Create(parameters); + +// No .ToParam() — reconstruct per variant. Implicit conversions from each +// *Param type to ContentBlockParam mean no explicit wrapper. +List assistantContent = []; +List toolResults = []; +foreach (ContentBlock block in response.Content) +{ + if (block.TryPickText(out TextBlock? text)) + { + assistantContent.Add(new TextBlockParam { Text = text.Text }); + } + else if (block.TryPickThinking(out ThinkingBlock? thinking)) + { + // Signature MUST be preserved — the API rejects tampering + assistantContent.Add(new ThinkingBlockParam + { + Thinking = thinking.Thinking, + Signature = thinking.Signature, + }); + } + else if (block.TryPickRedactedThinking(out RedactedThinkingBlock? redacted)) + { + assistantContent.Add(new RedactedThinkingBlockParam { Data = redacted.Data }); + } + else if (block.TryPickToolUse(out ToolUseBlock? toolUse)) + { + // ToolUseBlock has required Caller; ToolUseBlockParam.Caller is optional — don't copy it + assistantContent.Add(new ToolUseBlockParam + { + ID = toolUse.ID, + Name = toolUse.Name, + Input = toolUse.Input, + }); + // Execute the tool; collect ONE result per tool_use block — the API + // rejects the follow-up if any tool_use ID lacks a matching tool_result. + string result = ExecuteYourTool(toolUse.Name, toolUse.Input); + toolResults.Add(new ToolResultBlockParam + { + ToolUseID = toolUse.ID, + Content = result, + }); + } +} + +// Follow-up: prior messages + assistant echo + user tool_result(s) +List followUpMessages = +[ + .. parameters.Messages, + new() { Role = Role.Assistant, Content = assistantContent }, + new() { Role = Role.User, Content = toolResults }, +]; +``` + +`ToolResultBlockParam` has no tuple constructor — use the object initializer. `Content` is a string-or-list union; a plain `string` implicitly converts. + +--- + +## Context Editing / Compaction (Beta) + +**Beta-namespace prefix is inconsistent** (source-verified against `src/Anthropic/Models/Beta/Messages/*.cs` @ 12.9.0). No prefix: `MessageCreateParams`, `MessageCountTokensParams`, `Role`. **Everything else has the `Beta` prefix**: `BetaMessageParam`, `BetaMessage`, `BetaContentBlock`, `BetaToolUseBlock`, all block param types. The unprefixed `Role` WILL collide with `Anthropic.Models.Messages.Role` if you import both namespaces (CS0104). Safest: import only Beta; if mixing, alias the beta `Role`: + +```csharp +using Anthropic.Models.Beta.Messages; +using NonBeta = Anthropic.Models.Messages; // only if you also need non-beta types +// Now: MessageCreateParams, BetaMessageParam, Role (beta's), NonBeta.Role (if needed) +``` + + +`BetaMessage.Content` is `IReadOnlyList` — a 15-variant discriminated union. Narrow with `TryPick*`. **Response `BetaContentBlock` is NOT assignable to param `BetaContentBlockParam`** — there's no `.ToParam()` in C#. Round-trip by converting each block: + +```csharp +using Anthropic.Models.Beta.Messages; + +var betaParams = new MessageCreateParams // no Beta prefix — one of only 2 unprefixed +{ + Model = Model.ClaudeOpus4_6, + MaxTokens = 16000, + Betas = ["compact-2026-01-12"], + ContextManagement = new BetaContextManagementConfig + { + Edits = [new BetaCompact20260112Edit()], + }, + Messages = messages, +}; +BetaMessage resp = await client.Beta.Messages.Create(betaParams); + +foreach (BetaContentBlock block in resp.Content) +{ + if (block.TryPickCompaction(out BetaCompactionBlock? compaction)) + { + // Content is nullable — compaction can fail server-side + Console.WriteLine($"compaction summary: {compaction.Content}"); + } +} + +// Context-edit metadata lives on a separate nullable field +if (resp.ContextManagement is { } ctx) +{ + foreach (var edit in ctx.AppliedEdits) + Console.WriteLine($"cleared {edit.ClearedInputTokens} tokens"); +} + +// ROUND-TRIP: BetaMessageParam.Content is BetaMessageParamContent (a string|list +// union). It implicit-converts from List, NOT from the +// response's IReadOnlyList. Convert each block: +List paramBlocks = []; +foreach (var b in resp.Content) +{ + if (b.TryPickText(out var t)) paramBlocks.Add(new BetaTextBlockParam { Text = t.Text }); + else if (b.TryPickCompaction(out var c)) paramBlocks.Add(new BetaCompactionBlockParam { Content = c.Content }); + // ... other variants as needed +} +messages.Add(new BetaMessageParam { Role = Role.Assistant, Content = paramBlocks }); +``` + +All 15 `BetaContentBlock.TryPick*` variants: `Text`, `Thinking`, `RedactedThinking`, `ToolUse`, `ServerToolUse`, `WebSearchToolResult`, `WebFetchToolResult`, `CodeExecutionToolResult`, `BashCodeExecutionToolResult`, `TextEditorCodeExecutionToolResult`, `ToolSearchToolResult`, `McpToolUse`, `McpToolResult`, `ContainerUpload`, `Compaction`. + +**`BetaToolUseBlock.Input` is `IReadOnlyDictionary`** — index by key then call the `JsonElement` extractor: + +```csharp +if (block.TryPickToolUse(out BetaToolUseBlock? tu)) +{ + int a = tu.Input["a"].GetInt32(); + string s = tu.Input["name"].GetString()!; +} +``` + +--- + +## Effort Parameter + +Effort is nested under `OutputConfig`, NOT a top-level property. `ApiEnum` has an implicit conversion from the enum, so assign `Effort.High` directly. + +```csharp +OutputConfig = new OutputConfig { Effort = Effort.High }, +``` + +Values: `Effort.Low`, `Effort.Medium`, `Effort.High`, `Effort.Max`. Combine with `Thinking = new ThinkingConfigAdaptive()` for cost-quality control. + +--- + +## Prompt Caching + +`System` takes `MessageCreateParamsSystem?` — a union of `string` or `List`. There is no `SystemTextBlockParam`; use plain `TextBlockParam`. The implicit conversion needs the concrete `List` type (array literals won't convert). For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```csharp +System = new List { + new() { + Text = longSystemPrompt, + CacheControl = new CacheControlEphemeral(), // auto-sets Type = "ephemeral" + }, +}, +``` + +Optional `Ttl` on `CacheControlEphemeral`: `new() { Ttl = Ttl.Ttl1h }` or `Ttl.Ttl5m`. `CacheControl` also exists on `Tool.CacheControl` and top-level `MessageCreateParams.CacheControl`. + +Verify hits via `response.Usage.CacheCreationInputTokens` / `response.Usage.CacheReadInputTokens`. + +--- + +## Token Counting + +```csharp +MessageTokensCount result = await client.Messages.CountTokens(new MessageCountTokensParams { + Model = Model.ClaudeOpus4_6, + Messages = [new() { Role = Role.User, Content = "Hello" }], +}); +long tokens = result.InputTokens; +``` + +`MessageCountTokensParams.Tools` uses a different union type (`MessageCountTokensTool`) than `MessageCreateParams.Tools` (`ToolUnion`) — if you're passing tools, the compiler will tell you when it matters. + +--- + +## Structured Output + +```csharp +OutputConfig = new OutputConfig { + Format = new JsonOutputFormat { + Schema = new Dictionary { + ["type"] = JsonSerializer.SerializeToElement("object"), + ["properties"] = JsonSerializer.SerializeToElement( + new { name = new { type = "string" } }), + ["required"] = JsonSerializer.SerializeToElement(new[] { "name" }), + }, + }, +}, +``` + +`JsonOutputFormat.Type` is auto-set to `"json_schema"` by the constructor. `Schema` is `required`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` takes a `DocumentBlockParamSource` union: `Base64PdfSource` / `UrlPdfSource` / `PlainTextSource` / `ContentBlockSource`. `Base64PdfSource` auto-sets `MediaType = "application/pdf"` and `Type = "base64"`. + +```csharp +new MessageParam { + Role = Role.User, + Content = new List { + new DocumentBlockParam { Source = new Base64PdfSource { Data = base64String } }, + new TextBlockParam { Text = "Summarize this PDF" }, + }, +} +``` + +--- + +## Server-Side Tools + +Web search, bash, text editor, and code execution are built-in server tools. Type names are version-suffixed; constructors auto-set `name`/`type`. All implicit-convert to `ToolUnion`. + +```csharp +Tools = [ + new WebSearchTool20260209(), + new ToolBash20250124(), + new ToolTextEditor20250728(), + new CodeExecutionTool20260120(), +], +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`. `WebSearchTool20260209` optionals: `AllowedDomains`, `BlockedDomains`, `MaxUses`, `UserLocation`. + +--- + +## Files API (Beta) + +Files live under `client.Beta.Files` (namespace `Anthropic.Models.Beta.Files`). `BinaryContent` implicit-converts from `Stream` and `byte[]`. + +```csharp +using Anthropic.Models.Beta.Files; +using Anthropic.Models.Beta.Messages; + +FileMetadata meta = await client.Beta.Files.Upload( + new FileUploadParams { File = File.OpenRead("doc.pdf") }); + +// Referencing the uploaded file requires Beta message types: +new BetaRequestDocumentBlock { + Source = new BetaFileDocumentSource { FileID = meta.ID }, +} +``` + +The non-beta `DocumentBlockParamSource` union has no file-ID variant — file references need `client.Beta.Messages.Create()`. diff --git a/junie/versions/2285.4/skills/claude-api/curl/examples.md b/junie/versions/2285.4/skills/claude-api/curl/examples.md new file mode 100644 index 0000000..e08b443 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/curl/examples.md @@ -0,0 +1,216 @@ +# Claude API — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working in a language without an official SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" +``` + +--- + +## Basic Message Request + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "messages": [ + {"role": "user", "content": "What is the capital of France?"} + ] + }' +``` + +### Parsing the response + +Use `jq` to extract fields from the JSON response. Do not use `grep`/`sed` — +JSON strings can contain any character and regex parsing will break on quotes, +escapes, or multi-line content. + +```bash +# Capture the response, then extract fields +response=$(curl -s https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{"model":"claude-opus-4-6","max_tokens":16000,"messages":[{"role":"user","content":"Hello"}]}') + +# Print the first text block (-r strips the JSON quotes) +echo "$response" | jq -r '.content[0].text' + +# Read usage fields +input_tokens=$(echo "$response" | jq -r '.usage.input_tokens') +output_tokens=$(echo "$response" | jq -r '.usage.output_tokens') + +# Read stop reason (for tool-use loops) +stop_reason=$(echo "$response" | jq -r '.stop_reason') + +# Extract all text blocks (content is an array; filter to type=="text") +echo "$response" | jq -r '.content[] | select(.type == "text") | .text' +``` + + +--- + +## Streaming (SSE) + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 64000, + "stream": true, + "messages": [{"role": "user", "content": "Write a haiku"}] + }' +``` + +The response is a stream of Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` + +--- + +## Tool Use + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [{"role": "user", "content": "What is the weather in Paris?"}] + }' +``` + +When Claude responds with a `tool_use` block, send the result back: + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "tools": [{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": {"type": "string", "description": "City name"} + }, + "required": ["location"] + } + }], + "messages": [ + {"role": "user", "content": "What is the weather in Paris?"}, + {"role": "assistant", "content": [ + {"type": "text", "text": "Let me check the weather."}, + {"type": "tool_use", "id": "toolu_abc123", "name": "get_weather", "input": {"location": "Paris"}} + ]}, + {"role": "user", "content": [ + {"type": "tool_result", "tool_use_id": "toolu_abc123", "content": "72°F and sunny"} + ]} + ] + }' +``` + +--- + +## Prompt Caching + +Put `cache_control` on the last block of the stable prefix. See `shared/prompt-caching.md` for placement patterns and the silent-invalidator audit checklist. + +```bash +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} + ], + "messages": [{"role": "user", "content": "Summarize the key points"}] + }' +``` + +For 1-hour TTL: `"cache_control": {"type": "ephemeral", "ttl": "1h"}`. Top-level `"cache_control"` on the request body auto-places on the last cacheable block. Verify hits via the response `usage.cache_creation_input_tokens` / `usage.cache_read_input_tokens` fields. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `"type": "enabled"` with `"budget_tokens": N` (must be < `max_tokens`, min 1024). + +```bash +# Opus 4.6: adaptive thinking (recommended) +curl https://api.anthropic.com/v1/messages \ + -H "Content-Type: application/json" \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -d '{ + "model": "claude-opus-4-6", + "max_tokens": 16000, + "thinking": { + "type": "adaptive" + }, + "output_config": { + "effort": "high" + }, + "messages": [{"role": "user", "content": "Solve this step by step..."}] + }' +``` + +--- + +## Required Headers + +| Header | Value | Description | +| ------------------- | ------------------ | -------------------------- | +| `Content-Type` | `application/json` | Required | +| `x-api-key` | Your API key | Authentication | +| `anthropic-version` | `2023-06-01` | API version | +| `anthropic-beta` | Beta feature IDs | Required for beta features | diff --git a/junie/versions/2285.4/skills/claude-api/curl/managed-agents.md b/junie/versions/2285.4/skills/claude-api/curl/managed-agents.md new file mode 100644 index 0000000..3a684cf --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/curl/managed-agents.md @@ -0,0 +1,333 @@ +# Managed Agents — cURL / Raw HTTP + +Use these examples when the user needs raw HTTP requests or is working without an SDK. + +## Setup + +```bash +export ANTHROPIC_API_KEY="your-api-key" + +# Common headers +HEADERS=( + -H "Content-Type: application/json" + -H "x-api-key: $ANTHROPIC_API_KEY" + -H "anthropic-version: 2023-06-01" + -H "anthropic-beta: managed-agents-2026-04-01" +) +``` + +--- + +## Create an Environment + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "my-dev-env", + "config": { + "type": "cloud", + "networking": { "type": "unrestricted" } + } + }' +``` + +### With restricted networking + +```bash +curl -X POST https://api.anthropic.com/v1/environments \ + "${HEADERS[@]}" \ + -d '{ + "name": "restricted-env", + "config": { + "type": "cloud", + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } + } + }' +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Under `managed-agents-2026-04-01`, `model`/`system`/`tools` are top-level fields on `POST /v1/agents`, not on the session. Always create the agent first — the session only takes `"agent": {"type": "agent", "id": "..."}`. + +### Minimal + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Coding Assistant", + "model": "claude-opus-4-6", + "tools": [{ "type": "agent_toolset_20260401" }] + }' +# → { "id": "agent_abc123", ... } + +# 2. Start a session +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123" + }' +``` + +### With system prompt, custom tools, and GitHub repo + +```bash +# 1. Create the agent +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Code Reviewer", + "model": "claude-opus-4-6", + "system": "You are a senior code reviewer. Be thorough and constructive.", + "tools": [ + { "type": "agent_toolset_20260401" }, + { + "type": "custom", + "name": "run_linter", + "description": "Run the project linter on a file", + "input_schema": { + "type": "object", + "properties": { + "file_path": { "type": "string", "description": "Path to lint" } + }, + "required": ["file_path"] + } + } + ] + }' + +# 2. Start a session with the repo mounted +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": { "type": "agent", "id": "agent_abc123", "version": "1772585501101368014" }, + "environment_id": "env_abc123", + "title": "Code review session", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": "ghp_...", + "branch": "feature-branch" + } + ] + }' +``` + +--- + +## Send a User Message + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.message", + "content": [{ "type": "text", "text": "Review the auth module for security issues" }] + } + ] + }' +``` + +--- + +## Stream Events (SSE) + +```bash +curl -N https://api.anthropic.com/v1/sessions/$SESSION_ID/events/stream \ + "${HEADERS[@]}" +``` + +Response format: + +``` +event: session.status_running +data: {"type":"session.status_running","id":"sevt_...","processed_at":"..."} + +event: agent.message +data: {"type":"agent.message","id":"sevt_...","content":[{"type":"text","text":"I'll review..."}],"processed_at":"..."} + +event: session.status_idle +data: {"type":"session.status_idle","id":"sevt_...","processed_at":"..."} +``` + +--- + +## Poll Events + +```bash +# Get all events +curl https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" + +# Paginated — get next page of events +curl "https://api.anthropic.com/v1/sessions/$SESSION_ID/events?page=page_abc123" \ + "${HEADERS[@]}" +``` + +--- + +## Provide Custom Tool Result + +When the agent calls a custom tool, send the result back: + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "No linting errors found." }] + } + ] + }' +``` + +--- + +## Interrupt a Running Session + +```bash +curl -X POST https://api.anthropic.com/v1/sessions/$SESSION_ID/events \ + "${HEADERS[@]}" \ + -d '{ + "events": [ + { + "type": "interrupt" + } + ] + }' +``` + +--- + +## Get Session Details + +```bash +curl https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## List Sessions + +```bash +curl https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" +``` + +--- + +## Delete a Session + +```bash +curl -X DELETE https://api.anthropic.com/v1/sessions/$SESSION_ID \ + "${HEADERS[@]}" +``` + +--- + +## Upload a File + +```bash +curl -X POST https://api.anthropic.com/v1/files \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" \ + -H "anthropic-beta: files-api-2025-04-14" \ + -F "file=@path/to/file.txt" \ + -F "purpose=agent" +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```bash +# List files associated with a session +curl "https://api.anthropic.com/v1/files?scope=$SESSION_ID" \ + "${HEADERS[@]}" + +# Download a specific file +curl "https://api.anthropic.com/v1/files/$FILE_ID/content" \ + "${HEADERS[@]}" \ + -o downloaded_file.txt +``` + +--- + +## List Agents + +```bash +curl https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" +``` + +--- + +## MCP Server Integration + +```bash +# 1. Agent declares MCP server (no auth here — auth goes in a vault) +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "MCP Agent", + "model": "claude-opus-4-6", + "mcp_servers": [ + { "type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse" } + ], + "tools": [ + { "type": "agent_toolset_20260401" }, + { "type": "mcp_toolset", "mcp_server_name": "my-tools" } + ] + }' + +# 2. Session attaches vault containing credentials for that MCP server URL +curl -X POST https://api.anthropic.com/v1/sessions \ + "${HEADERS[@]}" \ + -d '{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] + }' +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Tool Configuration + +```bash +curl -X POST https://api.anthropic.com/v1/agents \ + "${HEADERS[@]}" \ + -d '{ + "name": "Restricted Agent", + "model": "claude-opus-4-6", + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] + }' +``` diff --git a/junie/versions/2285.4/skills/claude-api/go/claude-api.md b/junie/versions/2285.4/skills/claude-api/go/claude-api.md new file mode 100644 index 0000000..019b80f --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/go/claude-api.md @@ -0,0 +1,421 @@ +# Claude API — Go + +> **Note:** The Go SDK supports the Claude API and beta tool use with `BetaToolRunner`. Agent SDK is not yet available for Go. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) +``` + +--- + +## Basic Message Request + +```go +response, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is the capital of France?")), + }, +}) +if err != nil { + log.Fatal(err) +} +for _, block := range response.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + } +} +``` + +--- + +## Streaming + +```go +stream := client.Messages.NewStreaming(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 64000, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("Write a haiku")), + }, +}) + +for stream.Next() { + event := stream.Current() + switch eventVariant := event.AsAny().(type) { + case anthropic.ContentBlockDeltaEvent: + switch deltaVariant := eventVariant.Delta.AsAny().(type) { + case anthropic.TextDelta: + fmt.Print(deltaVariant.Text) + } + } +} +if err := stream.Err(); err != nil { + log.Fatal(err) +} +``` + +**Accumulating the final message** (there is no `GetFinalMessage()` on the stream): + +```go +stream := client.Messages.NewStreaming(ctx, params) +message := anthropic.Message{} +for stream.Next() { + message.Accumulate(stream.Current()) +} +if err := stream.Err(); err != nil { log.Fatal(err) } +// message.Content now has the complete response +``` + + +--- + +## Tool Use + +### Tool Runner (Beta — Recommended) + +**Beta:** The Go SDK provides `BetaToolRunner` for automatic tool use loops via the `toolrunner` package. + +```go +import ( + "context" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/toolrunner" +) + +// Define tool input with jsonschema tags for automatic schema generation +type GetWeatherInput struct { + City string `json:"city" jsonschema:"required,description=The city name"` +} + +// Create a tool with automatic schema generation from struct tags +weatherTool, err := toolrunner.NewBetaToolFromJSONSchema( + "get_weather", + "Get current weather for a city", + func(ctx context.Context, input GetWeatherInput) (anthropic.BetaToolResultBlockParamContentUnion, error) { + return anthropic.BetaToolResultBlockParamContentUnion{ + OfText: &anthropic.BetaTextBlockParam{ + Text: fmt.Sprintf("The weather in %s is sunny, 72°F", input.City), + }, + }, nil + }, +) +if err != nil { + log.Fatal(err) +} + +// Create a tool runner that handles the conversation loop automatically +runner := client.Beta.Messages.NewToolRunner( + []anthropic.BetaTool{weatherTool}, + anthropic.BetaToolRunnerParams{ + BetaMessageNewParams: anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, + MaxTokens: 16000, + Messages: []anthropic.BetaMessageParam{ + anthropic.NewBetaUserMessage(anthropic.NewBetaTextBlock("What's the weather in Paris?")), + }, + }, + MaxIterations: 5, + }, +) + +// Run until Claude produces a final response +message, err := runner.RunToCompletion(context.Background()) +if err != nil { + log.Fatal(err) +} + +// RunToCompletion returns *BetaMessage; content is []BetaContentBlockUnion. +// Narrow via AsAny() switch — note the Beta-namespace types (BetaTextBlock, +// not TextBlock): +for _, block := range message.Content { + switch block := block.AsAny().(type) { + case anthropic.BetaTextBlock: + fmt.Println(block.Text) + } +} +``` + +**Key features of the Go tool runner:** + +- Automatic schema generation from Go structs via `jsonschema` tags +- `RunToCompletion()` for simple one-shot usage +- `All()` iterator for processing each message in the conversation +- `NextMessage()` for step-by-step iteration +- Streaming variant via `NewToolRunnerStreaming()` with `AllStreaming()` + +### Manual Loop + +For fine-grained control over the agentic loop, define tools with `ToolParam`, check `StopReason`, execute tools yourself, and feed `tool_result` blocks back. This is the pattern when you need to intercept, validate, or log tool calls. + +Derived from `anthropic-sdk-go/examples/tools/main.go`. + +```go +package main + +import ( + "context" + "encoding/json" + "fmt" + "log" + + "github.com/anthropics/anthropic-sdk-go" +) + +func main() { + client := anthropic.NewClient() + + // 1. Define tools. ToolParam.InputSchema uses a map, no struct tags needed. + addTool := anthropic.ToolParam{ + Name: "add", + Description: anthropic.String("Add two integers"), + InputSchema: anthropic.ToolInputSchemaParam{ + Properties: map[string]any{ + "a": map[string]any{"type": "integer"}, + "b": map[string]any{"type": "integer"}, + }, + }, + } + // ToolParam must be wrapped in ToolUnionParam for the Tools slice + tools := []anthropic.ToolUnionParam{{OfTool: &addTool}} + + messages := []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("What is 2 + 3?")), + } + + for { + resp, err := client.Messages.New(context.Background(), anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Messages: messages, + Tools: tools, + }) + if err != nil { + log.Fatal(err) + } + + // 2. Append the assistant response to history BEFORE processing tool calls. + // resp.ToParam() converts Message → MessageParam in one call. + messages = append(messages, resp.ToParam()) + + // 3. Walk content blocks. ContentBlockUnion is a flattened struct; + // use block.AsAny().(type) to switch on the actual variant. + toolResults := []anthropic.ContentBlockParamUnion{} + for _, block := range resp.Content { + switch variant := block.AsAny().(type) { + case anthropic.TextBlock: + fmt.Println(variant.Text) + case anthropic.ToolUseBlock: + // 4. Parse the tool input. Use variant.JSON.Input.Raw() to get the + // raw JSON — block.Input is json.RawMessage, not the parsed value. + var in struct { + A int `json:"a"` + B int `json:"b"` + } + if err := json.Unmarshal([]byte(variant.JSON.Input.Raw()), &in); err != nil { + log.Fatal(err) + } + result := fmt.Sprintf("%d", in.A+in.B) + // 5. NewToolResultBlock(toolUseID, content, isError) builds the + // ContentBlockParamUnion for you. block.ID is the tool_use_id. + toolResults = append(toolResults, + anthropic.NewToolResultBlock(block.ID, result, false)) + } + } + + // 6. Exit when Claude stops asking for tools + if resp.StopReason != anthropic.StopReasonToolUse { + break + } + + // 7. Tool results go in a user message (variadic: all results in one turn) + messages = append(messages, anthropic.NewUserMessage(toolResults...)) + } +} +``` + +**Key API surface:** + +| Symbol | Purpose | +|---|---| +| `resp.ToParam()` | Convert `Message` response → `MessageParam` for history | +| `block.AsAny().(type)` | Type-switch on `ContentBlockUnion` variants | +| `variant.JSON.Input.Raw()` | Raw JSON string of tool input (for `json.Unmarshal`) | +| `anthropic.NewToolResultBlock(id, content, isError)` | Build `tool_result` block | +| `anthropic.NewUserMessage(blocks...)` | Wrap tool results as a user turn | +| `anthropic.StopReasonToolUse` | `StopReason` constant to check loop termination | +| `anthropic.ToolUnionParam{OfTool: &t}` | Wrap `ToolParam` in the union for `Tools:` | + +--- + +## Thinking + +Enable Claude's internal reasoning by setting `Thinking` in `MessageNewParams`. The response will contain `ThinkingBlock` content before the final `TextBlock`. + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. Combine with the `effort` parameter for cost-quality control. + +Derived from `anthropic-sdk-go/message.go` (`ThinkingConfigParamUnion`, `NewThinkingConfigAdaptiveParam`). + +```go +// There is no ThinkingConfigParamOfAdaptive helper — construct the union +// struct-literal directly and take the address of the variant. +adaptive := anthropic.NewThinkingConfigAdaptiveParam() +params := anthropic.MessageNewParams{ + Model: anthropic.ModelClaudeSonnet4_6, + MaxTokens: 16000, + Thinking: anthropic.ThinkingConfigParamUnion{OfAdaptive: &adaptive}, + Messages: []anthropic.MessageParam{ + anthropic.NewUserMessage(anthropic.NewTextBlock("How many r's in strawberry?")), + }, +} + +resp, err := client.Messages.New(context.Background(), params) +if err != nil { + log.Fatal(err) +} + +// ThinkingBlock(s) precede TextBlock in content +for _, block := range resp.Content { + switch b := block.AsAny().(type) { + case anthropic.ThinkingBlock: + fmt.Println("[thinking]", b.Thinking) + case anthropic.TextBlock: + fmt.Println(b.Text) + } +} +``` + +> **Deprecated:** `ThinkingConfigParamOfEnabled(budgetTokens)` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +To disable: `anthropic.ThinkingConfigParamUnion{OfDisabled: &anthropic.ThinkingConfigDisabledParam{}}`. + +--- + +## Prompt Caching + +`System` is `[]TextBlockParam`; set `CacheControl` on the last block to cache tools + system together. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```go +System: []anthropic.TextBlockParam{{ + Text: longSystemPrompt, + CacheControl: anthropic.NewCacheControlEphemeralParam(), // default 5m TTL +}}, +``` + +For 1-hour TTL: `anthropic.CacheControlEphemeralParam{TTL: anthropic.CacheControlEphemeralTTLTTL1h}`. There's also a top-level `CacheControl` on `MessageNewParams` that auto-places on the last cacheable block. + +Verify hits via `resp.Usage.CacheCreationInputTokens` / `resp.Usage.CacheReadInputTokens`. + +--- + +## Server-Side Tools + +Version-suffixed struct names with `Param` suffix. `Name`/`Type` are `constant.*` types — zero value marshals correctly, so `{}` works. Wrap in `ToolUnionParam` with the matching `Of*` field. + +```go +Tools: []anthropic.ToolUnionParam{ + {OfWebSearchTool20260209: &anthropic.WebSearchTool20260209Param{}}, + {OfBashTool20250124: &anthropic.ToolBash20250124Param{}}, + {OfTextEditor20250728: &anthropic.ToolTextEditor20250728Param{}}, + {OfCodeExecutionTool20260120: &anthropic.CodeExecutionTool20260120Param{}}, +}, +``` + +Also available: `WebFetchTool20260209Param`, `MemoryTool20250818Param`, `ToolSearchToolBm25_20251119Param`, `ToolSearchToolRegex20251119Param`. + +--- + +## PDF / Document Input + +`NewDocumentBlock` generic helper accepts any source type. `MediaType`/`Type` are auto-set. + +```go +b64 := base64.StdEncoding.EncodeToString(pdfBytes) + +msg := anthropic.NewUserMessage( + anthropic.NewDocumentBlock(anthropic.Base64PDFSourceParam{Data: b64}), + anthropic.NewTextBlock("Summarize this document"), +) +``` + +Other sources: `URLPDFSourceParam{URL: "https://..."}`, `PlainTextSourceParam{Data: "..."}`. + +--- + +## Files API (Beta) + +Under `client.Beta.Files`. Method is **`Upload`** (NOT `New`/`Create`), params struct is `BetaFileUploadParams`. The `File` field takes an `io.Reader`; use `anthropic.File()` to attach a filename + content-type for the multipart encoding. + +```go +f, _ := os.Open("./upload_me.txt") +defer f.Close() + +meta, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: anthropic.File(f, "upload_me.txt", "text/plain"), + Betas: []anthropic.AnthropicBeta{anthropic.AnthropicBetaFilesAPI2025_04_14}, +}) +// meta.ID is the file_id to reference in subsequent message requests +``` + +Other `Beta.Files` methods: `List`, `Delete`, `Download`, `GetMetadata`. + +--- + +## Context Editing / Compaction (Beta) + +Use `Beta.Messages.New` with `ContextManagement` on `BetaMessageNewParams`. There is no `NewBetaAssistantMessage` — use `.ToParam()` for the round-trip. + +```go +params := anthropic.BetaMessageNewParams{ + Model: anthropic.ModelClaudeOpus4_6, // also supported: ModelClaudeSonnet4_6 + MaxTokens: 16000, + Betas: []anthropic.AnthropicBeta{"compact-2026-01-12"}, + ContextManagement: anthropic.BetaContextManagementConfigParam{ + Edits: []anthropic.BetaContextManagementConfigEditUnionParam{ + {OfCompact20260112: &anthropic.BetaCompact20260112EditParam{}}, + }, + }, + Messages: []anthropic.BetaMessageParam{ /* ... */ }, +} + +resp, err := client.Beta.Messages.New(ctx, params) +if err != nil { + log.Fatal(err) +} + +// Round-trip: append response to history via .ToParam() +params.Messages = append(params.Messages, resp.ToParam()) + +// Read compaction blocks from the response +for _, block := range resp.Content { + if c, ok := block.AsAny().(anthropic.BetaCompactionBlock); ok { + fmt.Println("compaction summary:", c.Content) + } +} +``` + +Other edit types: `BetaClearToolUses20250919EditParam`, `BetaClearThinking20251015EditParam`. diff --git a/junie/versions/2285.4/skills/claude-api/go/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/go/managed-agents/README.md new file mode 100644 index 0000000..e7b855f --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/go/managed-agents/README.md @@ -0,0 +1,561 @@ +# Managed Agents — Go + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Go. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Go SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.New` and pass it to every subsequent `sessions.New`; do not call `agents.New` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +go get github.com/anthropics/anthropic-sdk-go +``` + +## Client Initialization + +```go +import ( + "context" + + "github.com/anthropics/anthropic-sdk-go" + "github.com/anthropics/anthropic-sdk-go/option" +) + +// Default (uses ANTHROPIC_API_KEY env var) +client := anthropic.NewClient() + +// Explicit API key +client := anthropic.NewClient( + option.WithAPIKey("your-api-key"), +) + +ctx := context.Background() +``` + +--- + +## Create an Environment + +```go +environment, err := client.Beta.Environments.New(ctx, anthropic.BetaEnvironmentNewParams{ + Name: "my-dev-env", + Config: anthropic.BetaCloudConfigParams{ + Networking: anthropic.BetaCloudConfigParamsNetworkingUnion{ + OfUnrestricted: &anthropic.UnrestrictedNetworkParam{}, + }, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(environment.ID) // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `Model`/`System`/`Tools` live on the agent object, not the session. Always start with `Beta.Agents.New()` — the session only takes `Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}` (or the typed `OfBetaManagedAgentsAgents` variant when you need a specific version). + +### Minimal + +```go +// 1. Create the agent (reusable, versioned) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "Coding Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + System: anthropic.String("You are a helpful coding assistant."), + Tools: []anthropic.BetaAgentNewParamsToolUnion{{ + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }}, +}) +if err != nil { + panic(err) +} + +// 2. Start a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + Title: anthropic.String("Quickstart session"), +}) +if err != nil { + panic(err) +} +fmt.Printf("Session ID: %s, status: %s\n", session.ID, session.Status) +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```go +updatedAgent, err := client.Beta.Agents.Update(ctx, agent.ID, anthropic.BetaAgentUpdateParams{ + Version: agent.Version, + System: anthropic.String("You are a helpful coding agent. Always write tests."), +}) +if err != nil { + panic(err) +} +fmt.Printf("New version: %d\n", updatedAgent.Version) + +// List all versions +iter := client.Beta.Agents.Versions.ListAutoPaging(ctx, agent.ID, anthropic.BetaAgentVersionListParams{}) +for iter.Next() { + version := iter.Current() + fmt.Printf("Version %d: %s\n", version.Version, version.UpdatedAt.Format(time.RFC3339)) +} +if err := iter.Err(); err != nil { + panic(err) +} + +// Archive the agent +_, err = client.Beta.Agents.Archive(ctx, agent.ID, anthropic.BetaAgentArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## Send a User Message + +```go +_, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Review the auth module", + }, + }}, + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```go +// Open the stream first, then send the user message +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +if _, err := client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{ + Events: []anthropic.SendEventsParamsUnion{{ + OfUserMessage: &anthropic.BetaManagedAgentsUserMessageEventParams{ + Type: anthropic.BetaManagedAgentsUserMessageEventParamsTypeUserMessage, + Content: []anthropic.BetaManagedAgentsUserMessageEventParamsContentUnion{{ + OfText: &anthropic.BetaManagedAgentsTextBlockParam{ + Type: anthropic.BetaManagedAgentsTextBlockTypeText, + Text: "Summarize the repo README", + }, + }}, + }, + }}, +}); err != nil { + panic(err) +} + +events: +for stream.Next() { + switch event := stream.Current().AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsAgentToolUseEvent: + fmt.Printf("\n[Using tool: %s]\n", event.Name) + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break events + case anthropic.BetaManagedAgentsSessionErrorEvent: + fmt.Printf("\n[Error: %s]\n", event.Error.Message) + break events + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```go +stream := client.Beta.Sessions.Events.StreamEvents(ctx, session.ID, anthropic.BetaSessionEventStreamParams{}) +defer stream.Close() + +// Stream is open and buffering. List history before tailing live. +seenEventIDs := map[string]struct{}{} +history := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for history.Next() { + seenEventIDs[history.Current().ID] = struct{}{} +} +if err := history.Err(); err != nil { + panic(err) +} + +// Tail live events, skipping anything already seen +tail: +for stream.Next() { + event := stream.Current() + if _, seen := seenEventIDs[event.ID]; seen { + continue + } + seenEventIDs[event.ID] = struct{}{} + switch event := event.AsAny().(type) { + case anthropic.BetaManagedAgentsAgentMessageEvent: + for _, block := range event.Content { + fmt.Print(block.Text) + } + case anthropic.BetaManagedAgentsSessionStatusIdleEvent: + break tail + } +} +if err := stream.Err(); err != nil { + panic(err) +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Go managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `github.com/anthropics/anthropic-sdk-go` repository for the corresponding Go params types. + +--- + +## Poll Events + +```go +// Auto-paginating iterator +iter := client.Beta.Sessions.Events.ListAutoPaging(ctx, session.ID, anthropic.BetaSessionEventListParams{}) +for iter.Next() { + event := iter.Current() + fmt.Printf("%s: %s\n", event.Type, event.ID) +} +if err := iter.Err(); err != nil { + panic(err) +} +``` + +--- + +## Upload a File + +```go +csvFile, err := os.Open("data.csv") +if err != nil { + panic(err) +} +defer csvFile.Close() + +file, err := client.Beta.Files.Upload(ctx, anthropic.BetaFileUploadParams{ + File: csvFile, +}) +if err != nil { + panic(err) +} +fmt.Printf("File ID: %s\n", file.ID) + +// Mount in a session +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfString: anthropic.String(agent.ID), + }, + EnvironmentID: environment.ID, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{{ + OfFile: &anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + MountPath: anthropic.String("/workspace/data.csv"), + }, + }}, +}) +if err != nil { + panic(err) +} +``` + +### Add and Manage Resources on an Existing Session + +```go +// Attach an additional file to an open session +resource, err := client.Beta.Sessions.Resources.Add(ctx, session.ID, anthropic.BetaSessionResourceAddParams{ + BetaManagedAgentsFileResourceParams: anthropic.BetaManagedAgentsFileResourceParams{ + Type: anthropic.BetaManagedAgentsFileResourceParamsTypeFile, + FileID: file.ID, + }, +}) +if err != nil { + panic(err) +} +fmt.Println(resource.ID) // "sesrsc_01ABC..." + +// List resources on the session +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +for _, entry := range listed.Data { + fmt.Println(entry.ID, entry.Type) +} + +// Detach a resource +if _, err := client.Beta.Sessions.Resources.Delete(ctx, resource.ID, anthropic.BetaSessionResourceDeleteParams{ + SessionID: session.ID, +}); err != nil { + panic(err) +} +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Go in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `github.com/anthropics/anthropic-sdk-go` repository for the `Beta.Files.List` and `Beta.Files.Download` Go params types. + +--- + +## Session Management + +```go +// List environments +environments, err := client.Beta.Environments.List(ctx, anthropic.BetaEnvironmentListParams{}) +if err != nil { + panic(err) +} + +// Retrieve a specific environment +env, err := client.Beta.Environments.Get(ctx, environment.ID, anthropic.BetaEnvironmentGetParams{}) +if err != nil { + panic(err) +} + +// Archive an environment (read-only, existing sessions continue) +_, err = client.Beta.Environments.Archive(ctx, environment.ID, anthropic.BetaEnvironmentArchiveParams{}) +if err != nil { + panic(err) +} + +// Delete an environment (only if no sessions reference it) +_, err = client.Beta.Environments.Delete(ctx, environment.ID, anthropic.BetaEnvironmentDeleteParams{}) +if err != nil { + panic(err) +} + +// Delete a session +_, err = client.Beta.Sessions.Delete(ctx, session.ID, anthropic.BetaSessionDeleteParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## MCP Server Integration + +```go +// Agent declares MCP server (no auth here — auth goes in a vault) +agent, err := client.Beta.Agents.New(ctx, anthropic.BetaAgentNewParams{ + Name: "GitHub Assistant", + Model: anthropic.BetaManagedAgentsModelConfigParams{ + ID: "claude-opus-4-6", + Type: anthropic.BetaManagedAgentsModelConfigParamsTypeModelConfig, + }, + MCPServers: []anthropic.BetaManagedAgentsUrlmcpServerParams{{ + Type: anthropic.BetaManagedAgentsUrlmcpServerParamsTypeURL, + Name: "github", + URL: "https://api.githubcopilot.com/mcp/", + }}, + Tools: []anthropic.BetaAgentNewParamsToolUnion{ + { + OfAgentToolset20260401: &anthropic.BetaManagedAgentsAgentToolset20260401Params{ + Type: anthropic.BetaManagedAgentsAgentToolset20260401ParamsTypeAgentToolset20260401, + }, + }, + { + OfMCPToolset: &anthropic.BetaManagedAgentsMCPToolsetParams{ + Type: anthropic.BetaManagedAgentsMCPToolsetParamsTypeMCPToolset, + MCPServerName: "github", + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Session attaches vault(s) containing credentials for those MCP server URLs +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{ + OfBetaManagedAgentsAgents: &anthropic.BetaManagedAgentsAgentParams{ + Type: anthropic.BetaManagedAgentsAgentParamsTypeAgent, + ID: agent.ID, + Version: anthropic.Int(agent.Version), + }, + }, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, +}) +if err != nil { + panic(err) +} +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```go +// Create a vault +vault, err := client.Beta.Vaults.New(ctx, anthropic.BetaVaultNewParams{ + DisplayName: "Alice", + Metadata: map[string]string{"external_user_id": "usr_abc123"}, +}) +if err != nil { + panic(err) +} + +// Add an OAuth credential +credential, err := client.Beta.Vaults.Credentials.New(ctx, vault.ID, anthropic.BetaVaultCredentialNewParams{ + DisplayName: anthropic.String("Alice's Slack"), + Auth: anthropic.BetaVaultCredentialNewParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthCreateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthCreateParamsTypeMCPOAuth, + MCPServerURL: "https://mcp.slack.com/mcp", + AccessToken: "xoxp-...", + ExpiresAt: anthropic.Time(time.Date(2026, time.April, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshParams{ + TokenEndpoint: "https://slack.com/api/oauth.v2.access", + ClientID: "1234567890.0987654321", + Scope: anthropic.String("channels:read chat:write"), + RefreshToken: "xoxe-1-...", + TokenEndpointAuth: anthropic.BetaManagedAgentsMCPOAuthRefreshParamsTokenEndpointAuthUnion{ + OfClientSecretPost: &anthropic.BetaManagedAgentsTokenEndpointAuthPostParam{ + Type: anthropic.BetaManagedAgentsTokenEndpointAuthPostParamTypeClientSecretPost, + ClientSecret: "abc123...", + }, + }, + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Rotate the credential (e.g., after a token refresh) +_, err = client.Beta.Vaults.Credentials.Update(ctx, credential.ID, anthropic.BetaVaultCredentialUpdateParams{ + VaultID: vault.ID, + Auth: anthropic.BetaVaultCredentialUpdateParamsAuthUnion{ + OfMCPOAuth: &anthropic.BetaManagedAgentsMCPOAuthUpdateParams{ + Type: anthropic.BetaManagedAgentsMCPOAuthUpdateParamsTypeMCPOAuth, + AccessToken: anthropic.String("xoxp-new-..."), + ExpiresAt: anthropic.Time(time.Date(2026, time.May, 15, 0, 0, 0, 0, time.UTC)), + Refresh: anthropic.BetaManagedAgentsMCPOAuthRefreshUpdateParams{ + RefreshToken: anthropic.String("xoxe-1-new-..."), + }, + }, + }, +}) +if err != nil { + panic(err) +} + +// Archive a vault +_, err = client.Beta.Vaults.Archive(ctx, vault.ID, anthropic.BetaVaultArchiveParams{}) +if err != nil { + panic(err) +} +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```go +session, err := client.Beta.Sessions.New(ctx, anthropic.BetaSessionNewParams{ + Agent: anthropic.BetaSessionNewParamsAgentUnion{OfString: anthropic.String(agent.ID)}, + EnvironmentID: environment.ID, + VaultIDs: []string{vault.ID}, + Resources: []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/repo", + MountPath: anthropic.String("/workspace/repo"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + }, +}) +if err != nil { + panic(err) +} +``` + +Multiple repositories on the same session: + +```go +resources := []anthropic.BetaSessionNewParamsResourceUnion{ + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/frontend", + MountPath: anthropic.String("/workspace/frontend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, + { + OfGitHubRepository: &anthropic.BetaManagedAgentsGitHubRepositoryResourceParams{ + Type: anthropic.BetaManagedAgentsGitHubRepositoryResourceParamsTypeGitHubRepository, + URL: "https://github.com/org/backend", + MountPath: anthropic.String("/workspace/backend"), + AuthorizationToken: "ghp_your_github_token", + }, + }, +} +``` + +Rotating a repository's authorization token: + +```go +listed, err := client.Beta.Sessions.Resources.List(ctx, session.ID, anthropic.BetaSessionResourceListParams{}) +if err != nil { + panic(err) +} +repoResourceID := listed.Data[0].ID + +_, err = client.Beta.Sessions.Resources.Update(ctx, repoResourceID, anthropic.BetaSessionResourceUpdateParams{ + SessionID: session.ID, + AuthorizationToken: "ghp_your_new_github_token", +}) +if err != nil { + panic(err) +} +``` diff --git a/junie/versions/2285.4/skills/claude-api/java/claude-api.md b/junie/versions/2285.4/skills/claude-api/java/claude-api.md new file mode 100644 index 0000000..22f872e --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/java/claude-api.md @@ -0,0 +1,432 @@ +# Claude API — Java + +> **Note:** The Java SDK supports the Claude API and beta tool use with annotated classes. Agent SDK is not yet available for Java. + +## Installation + +Maven: + +```xml + + com.anthropic + anthropic-java + 2.17.0 + +``` + +Gradle: + +```groovy +implementation("com.anthropic:anthropic-java:2.17.0") +``` + +## Client Initialization + +```java +import com.anthropic.client.AnthropicClient; +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (reads ANTHROPIC_API_KEY from environment) +AnthropicClient client = AnthropicOkHttpClient.fromEnv(); + +// Explicit API key +AnthropicClient client = AnthropicOkHttpClient.builder() + .apiKey("your-api-key") + .build(); +``` + +--- + +## Basic Message Request + +```java +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Message; +import com.anthropic.models.messages.Model; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addUserMessage("What is the capital of France?") + .build(); + +Message response = client.messages().create(params); +response.content().stream() + .flatMap(block -> block.text().stream()) + .forEach(textBlock -> System.out.println(textBlock.text())); +``` + +--- + +## Streaming + +```java +import com.anthropic.core.http.StreamResponse; +import com.anthropic.models.messages.RawMessageStreamEvent; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(64000L) + .addUserMessage("Write a haiku") + .build(); + +try (StreamResponse streamResponse = client.messages().createStreaming(params)) { + streamResponse.stream() + .flatMap(event -> event.contentBlockDelta().stream()) + .flatMap(deltaEvent -> deltaEvent.delta().text().stream()) + .forEach(textDelta -> System.out.print(textDelta.text())); +} +``` + +--- + +## Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. The builder has a direct `.thinking(ThinkingConfigAdaptive)` overload — no manual union wrapping. + +```java +import com.anthropic.models.messages.ContentBlock; +import com.anthropic.models.messages.MessageCreateParams; +import com.anthropic.models.messages.Model; +import com.anthropic.models.messages.ThinkingConfigAdaptive; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .thinking(ThinkingConfigAdaptive.builder().build()) + .addUserMessage("Solve this step by step: 27 * 453") + .build(); + +for (ContentBlock block : client.messages().create(params).content()) { + block.thinking().ifPresent(t -> System.out.println("[thinking] " + t.thinking())); + block.text().ifPresent(t -> System.out.println(t.text())); +} +``` + +> **Deprecated:** `ThinkingConfigEnabled.builder().budgetTokens(N)` (and the `.enabledThinking(N)` shortcut) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`ContentBlock` narrowing: `.thinking()` / `.text()` return `Optional` — use `.ifPresent(...)` or `.stream().flatMap(...)`. Alternative: `isThinking()` / `asThinking()` boolean+unwrap pairs (throws on wrong variant). + +--- + +## Tool Use (Beta) + +The Java SDK supports beta tool use with annotated classes. Tool classes implement `Supplier` for automatic execution via `BetaToolRunner`. + +### Tool Runner (automatic loop) + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.helpers.BetaToolRunner; +import com.fasterxml.jackson.annotation.JsonClassDescription; +import com.fasterxml.jackson.annotation.JsonPropertyDescription; +import java.util.function.Supplier; + +@JsonClassDescription("Get the weather in a given location") +static class GetWeather implements Supplier { + @JsonPropertyDescription("The city and state, e.g. San Francisco, CA") + public String location; + + @Override + public String get() { + return "The weather in " + location + " is sunny and 72°F"; + } +} + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(16000L) + .putAdditionalHeader("anthropic-beta", "structured-outputs-2025-11-13") + .addTool(GetWeather.class) + .addUserMessage("What's the weather in San Francisco?") + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +### Memory Tool + +The Java SDK provides `BetaMemoryToolHandler` for implementing the memory tool backend. You supply a handler that manages file storage, and the `BetaToolRunner` handles memory tool calls automatically. + +```java +import com.anthropic.helpers.BetaMemoryToolHandler; +import com.anthropic.helpers.BetaToolRunner; +import com.anthropic.models.beta.messages.BetaMemoryTool20250818; +import com.anthropic.models.beta.messages.BetaMessage; +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.ToolRunnerCreateParams; + +// Implement BetaMemoryToolHandler with your storage backend (e.g., filesystem) +BetaMemoryToolHandler memoryHandler = new FileSystemMemoryToolHandler(sandboxRoot); + +MessageCreateParams createParams = MessageCreateParams.builder() + .model("claude-opus-4-6") + .maxTokens(4096L) + .addTool(BetaMemoryTool20250818.builder().build()) + .addUserMessage("Remember that my favorite color is blue") + .build(); + +BetaToolRunner toolRunner = client.beta().messages().toolRunner( + ToolRunnerCreateParams.builder() + .betaMemoryToolHandler(memoryHandler) + .initialMessageParams(createParams) + .build()); + +for (BetaMessage message : toolRunner) { + System.out.println(message); +} +``` + +See the [shared memory tool concepts](../shared/tool-use-concepts.md) for more details on the memory tool. + +### Non-Beta Tool Declaration (manual JSON schema) + +`Tool.InputSchema.Properties` is a freeform `Map` wrapper — build property schemas via `putAdditionalProperty`. `type: "object"` is the default. The builder has a direct `.addTool(Tool)` overload that wraps in `ToolUnion` automatically. + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.messages.Tool; + +Tool tool = Tool.builder() + .name("get_weather") + .description("Get the current weather in a given location") + .inputSchema(Tool.InputSchema.builder() + .properties(Tool.InputSchema.Properties.builder() + .putAdditionalProperty("location", JsonValue.from(Map.of("type", "string"))) + .build()) + .required(List.of("location")) + .build()) + .build(); + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .addTool(tool) + .addUserMessage("Weather in Paris?") + .build(); +``` + +For manual tool loops, handle `tool_use` blocks in the response, send `tool_result` back, loop until `stop_reason` is `"end_turn"`. See [shared tool use concepts](../shared/tool-use-concepts.md). + +### Building `MessageParam` with Content Blocks (Tool Result Round-Trip) + +`MessageParam.Content` is an inner union class (string | list). Use the builder's `.contentOfBlockParams(List)` alias — there is NO separate `MessageParamContent` class with a static `ofBlockParams`: + +```java +import com.anthropic.models.messages.MessageParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.ToolResultBlockParam; + +List results = List.of( + ContentBlockParam.ofToolResult(ToolResultBlockParam.builder() + .toolUseId(toolUseBlock.id()) + .content(yourResultString) + .build()) +); + +MessageParam toolResultMsg = MessageParam.builder() + .role(MessageParam.Role.USER) + .contentOfBlockParams(results) // builder alias for Content.ofBlockParams(...) + .build(); +``` + +--- + +## Effort Parameter + +Effort is nested inside `OutputConfig` — there is NO `.effort()` directly on `MessageCreateParams.Builder`. + +```java +import com.anthropic.models.messages.OutputConfig; + +.outputConfig(OutputConfig.builder() + .effort(OutputConfig.Effort.HIGH) // or LOW, MEDIUM, MAX + .build()) +``` + +Combine with `Thinking = ThinkingConfigAdaptive` for cost-quality control. + +--- + +## Prompt Caching + +System message as a list of `TextBlockParam` with `CacheControlEphemeral`. Use `.systemOfTextBlockParams(...)` — the plain `.system(String)` overload can't carry cache control. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```java +import com.anthropic.models.messages.TextBlockParam; +import com.anthropic.models.messages.CacheControlEphemeral; + +.systemOfTextBlockParams(List.of( + TextBlockParam.builder() + .text(longSystemPrompt) + .cacheControl(CacheControlEphemeral.builder() + .ttl(CacheControlEphemeral.Ttl.TTL_1H) // optional; also TTL_5M + .build()) + .build())) +``` + +There's also a top-level `.cacheControl(CacheControlEphemeral)` on `MessageCreateParams.Builder` and on `Tool.builder()`. + +Verify hits via `response.usage().cacheCreationInputTokens()` / `response.usage().cacheReadInputTokens()`. + +--- + +## Token Counting + +```java +import com.anthropic.models.messages.MessageCountTokensParams; + +long tokens = client.messages().countTokens( + MessageCountTokensParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .addUserMessage("Hello") + .build() +).inputTokens(); +``` + +--- + +## Structured Output + +The class-based overload auto-derives the JSON schema from your POJO and gives you a typed `.text()` return — no manual schema, no manual parsing. + +```java +import com.anthropic.models.messages.StructuredMessageCreateParams; + +record Book(String title, String author) {} +record BookList(List books) {} + +StructuredMessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_SONNET_4_6) + .maxTokens(16000L) + .outputConfig(BookList.class) // returns a typed builder + .addUserMessage("List 3 classic novels") + .build(); + +client.messages().create(params).content().stream() + .flatMap(cb -> cb.text().stream()) + .forEach(typed -> { + // typed.text() returns BookList, not String + for (Book b : typed.text().books()) System.out.println(b.title()); + }); +``` + +Supports Jackson annotations: `@JsonPropertyDescription`, `@JsonIgnore`, `@ArraySchema(minItems=...)`. Manual schema path: `OutputConfig.builder().format(JsonOutputFormat.builder().schema(...).build())`. + +--- + +## PDF / Document Input + +`DocumentBlockParam` builder has source shortcuts. Wrap in `ContentBlockParam.ofDocument()` and pass via `.addUserMessageOfBlockParams()`. + +```java +import com.anthropic.models.messages.DocumentBlockParam; +import com.anthropic.models.messages.ContentBlockParam; +import com.anthropic.models.messages.TextBlockParam; + +DocumentBlockParam doc = DocumentBlockParam.builder() + .base64Source(base64String) // or .urlSource("https://...") or .textSource("...") + .title("My Document") // optional + .build(); + +.addUserMessageOfBlockParams(List.of( + ContentBlockParam.ofDocument(doc), + ContentBlockParam.ofText(TextBlockParam.builder().text("Summarize this").build()))) +``` + +--- + +## Server-Side Tools + +Version-suffixed types; `name`/`type` auto-set by builder. Direct `.addTool()` overloads exist for every type — no manual `ToolUnion` wrapping. + +```java +import com.anthropic.models.messages.WebSearchTool20260209; +import com.anthropic.models.messages.ToolBash20250124; +import com.anthropic.models.messages.ToolTextEditor20250728; +import com.anthropic.models.messages.CodeExecutionTool20260120; + +.addTool(WebSearchTool20260209.builder() + .maxUses(5L) // optional + .allowedDomains(List.of("example.com")) // optional + .build()) +.addTool(ToolBash20250124.builder().build()) +.addTool(ToolTextEditor20250728.builder().build()) +.addTool(CodeExecutionTool20260120.builder().build()) +``` + +Also available: `WebFetchTool20260209`, `MemoryTool20250818`, `ToolSearchToolBm25_20251119`. + +### Beta namespace (MCP, compaction) + +For beta-only features use `com.anthropic.models.beta.messages.*` — class names have a `Beta` prefix AND live in the beta package. The beta `MessageCreateParams.Builder` has direct `.addTool(BetaToolBash20250124)` overloads AND `.addMcpServer()`: + +```java +import com.anthropic.models.beta.messages.MessageCreateParams; +import com.anthropic.models.beta.messages.BetaToolBash20250124; +import com.anthropic.models.beta.messages.BetaCodeExecutionTool20260120; +import com.anthropic.models.beta.messages.BetaRequestMcpServerUrlDefinition; + +MessageCreateParams params = MessageCreateParams.builder() + .model(Model.CLAUDE_OPUS_4_6) + .maxTokens(16000L) + .addBeta("mcp-client-2025-11-20") + .addTool(BetaToolBash20250124.builder().build()) + .addTool(BetaCodeExecutionTool20260120.builder().build()) + .addMcpServer(BetaRequestMcpServerUrlDefinition.builder() + .name("my-server") + .url("https://example.com/mcp") + .build()) + .addUserMessage("...") + .build(); + +client.beta().messages().create(params); +``` + +`BetaTool*` types are NOT interchangeable with non-beta `Tool*` — pick one namespace per request. + +**Reading server-tool blocks in the response:** `ServerToolUseBlock` has `.id()`, `.name()` (enum), and `._input()` returning raw `JsonValue` — there is NO typed `.input()`. For code execution results, unwrap two levels: + +```java +for (ContentBlock block : response.content()) { + block.serverToolUse().ifPresent(stu -> { + System.out.println("tool: " + stu.name() + " input: " + stu._input()); + }); + block.codeExecutionToolResult().ifPresent(r -> { + r.content().resultBlock().ifPresent(result -> { + System.out.println("stdout: " + result.stdout()); + System.out.println("stderr: " + result.stderr()); + System.out.println("exit: " + result.returnCode()); + }); + }); +} +``` + +--- + +## Files API (Beta) + +Under `client.beta().files()`. File references in messages need the beta message types (non-beta `DocumentBlockParam.Source` has no file-ID variant). + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.files.FileMetadata; +import com.anthropic.models.beta.messages.BetaRequestDocumentBlock; +import java.nio.file.Paths; + +FileMetadata meta = client.beta().files().upload( + FileUploadParams.builder() + .file(Paths.get("/path/to/doc.pdf")) // or .file(InputStream) or .file(byte[]) + .build()); + +// Reference in a beta message: +BetaRequestDocumentBlock doc = BetaRequestDocumentBlock.builder() + .fileSource(meta.id()) + .build(); +``` + +Other methods: `.list()`, `.delete(String fileId)`, `.download(String fileId)`, `.retrieveMetadata(String fileId)`. diff --git a/junie/versions/2285.4/skills/claude-api/java/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/java/managed-agents/README.md new file mode 100644 index 0000000..49398bc --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/java/managed-agents/README.md @@ -0,0 +1,442 @@ +# Managed Agents — Java + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Java. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Java SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta().agents().create` and pass it to every subsequent `client.beta().sessions().create`; do not call `agents().create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```xml + + com.anthropic + anthropic-java + +``` + +## Client Initialization + +```java +import com.anthropic.client.okhttp.AnthropicOkHttpClient; + +// Default (uses ANTHROPIC_API_KEY env var) +var client = AnthropicOkHttpClient.fromEnv(); +``` + +--- + +## Create an Environment + +```java +import com.anthropic.models.beta.environments.BetaCloudConfigParams; +import com.anthropic.models.beta.environments.EnvironmentCreateParams; +import com.anthropic.models.beta.environments.UnrestrictedNetwork; + +var environment = client.beta().environments().create(EnvironmentCreateParams.builder() + .name("my-dev-env") + .config(BetaCloudConfigParams.builder() + .networking(UnrestrictedNetwork.builder().build()) + .build()) + .build()); +System.out.println("Environment ID: " + environment.id()); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** Model, system, and tools live on the agent object, not the session. Always start with `client.beta().agents().create()` — the session takes either `.agent(agent.id())` or the typed `BetaManagedAgentsAgentParams.builder()...build()`. + +### Minimal + +```java +import com.anthropic.models.beta.agents.AgentCreateParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsAgentToolset20260401Params; +import com.anthropic.models.beta.sessions.BetaManagedAgentsAgentParams; +import com.anthropic.models.beta.sessions.SessionCreateParams; + +// 1. Create the agent (reusable, versioned) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("Coding Assistant") + .model("claude-opus-4-6") + .system("You are a helpful coding assistant.") + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .build()); + +// 2. Start a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .title("Quickstart session") + .build()); +System.out.println("Session ID: " + session.id()); +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```java +import com.anthropic.models.beta.agents.AgentUpdateParams; + +var updatedAgent = client.beta().agents().update(agent.id(), AgentUpdateParams.builder() + .version(agent.version()) + .system("You are a helpful coding agent. Always write tests.") + .build()); +System.out.println("New version: " + updatedAgent.version()); + +// List all versions +for (var version : client.beta().agents().versions().list(agent.id()).autoPager()) { + System.out.println("Version " + version.version() + ": " + version.updatedAt()); +} + +// Archive the agent +var archived = client.beta().agents().archive(agent.id()); +System.out.println("Archived at: " + archived.archivedAt().orElseThrow()); +``` + +--- + +## Send a User Message + +```java +import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserMessageEventParams; +import com.anthropic.models.beta.sessions.events.EventSendParams; + +client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Review the auth module") + .build()) + .build()); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```java +import com.anthropic.models.beta.sessions.events.StreamEvents; + +// Open the stream first, then send the user message +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + client.beta().sessions().events().send(session.id(), EventSendParams.builder() + .addEvent(BetaManagedAgentsUserMessageEventParams.builder() + .type(BetaManagedAgentsUserMessageEventParams.Type.USER_MESSAGE) + .addTextContent("Summarize the repo README") + .build()) + .build()); + + for (var event : (Iterable) stream.stream()::iterator) { + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isAgentToolUse()) { + System.out.println("\n[Using tool: " + event.asAgentToolUse().name() + "]"); + } else if (event.isSessionStatusIdle()) { + break; + } else if (event.isSessionError()) { + System.out.println("\n[Error]"); + break; + } + } +} +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events. The cross-variant `id` field is read from the raw `_json()` value: + +```java +import com.anthropic.core.JsonValue; +import java.util.HashSet; +import java.util.Map; +import java.util.Optional; + +try (var stream = client.beta().sessions().events().streamStreaming(session.id())) { + // Stream is open and buffering. List history before tailing live. + var seenEventIds = new HashSet(); + for (var past : client.beta().sessions().events().list(session.id()).autoPager()) { + Optional> obj = past._json().orElseThrow().asObject(); + seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow()); + } + + // Tail live events, skipping anything already seen + for (var event : (Iterable) stream.stream()::iterator) { + Optional> obj = event._json().orElseThrow().asObject(); + if (!seenEventIds.add(obj.orElseThrow().get("id").asStringOrThrow())) continue; + if (event.isAgentMessage()) { + event.asAgentMessage().content().forEach(block -> System.out.print(block.text())); + } else if (event.isSessionStatusIdle()) { + break; + } + } +} +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Java managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-java` repository for the corresponding params types. + +--- + +## Poll Events + +```java +for (var event : client.beta().sessions().events().list(session.id()).autoPager()) { + System.out.println(event.type() + ": " + event); +} +``` + +--- + +## Upload a File + +```java +import com.anthropic.models.beta.files.FileUploadParams; +import com.anthropic.models.beta.sessions.BetaManagedAgentsFileResourceParams; +import java.nio.file.Path; + +var dataCsv = Path.of("data.csv"); + +var file = client.beta().files().upload(FileUploadParams.builder() + .file(dataCsv) + .build()); +System.out.println("File ID: " + file.id()); + +// Mount in a session +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addResource(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .mountPath("/workspace/data.csv") + .build()) + .build()); +``` + +### Add and Manage Resources on an Existing Session + +```java +import com.anthropic.models.beta.sessions.resources.ResourceAddParams; +import com.anthropic.models.beta.sessions.resources.ResourceDeleteParams; + +// Attach an additional file to an open session +var resource = client.beta().sessions().resources().add(session.id(), ResourceAddParams.builder() + .betaManagedAgentsFileResourceParams(BetaManagedAgentsFileResourceParams.builder() + .type(BetaManagedAgentsFileResourceParams.Type.FILE) + .fileId(file.id()) + .build()) + .build()); +System.out.println(resource.id()); // "sesrsc_01ABC..." + +// List resources on the session — entries are a discriminated union +var listed = client.beta().sessions().resources().list(session.id()); +for (var entry : listed.data()) { + if (entry.isFile()) { + var fileResource = entry.asFile(); + System.out.println(fileResource.id() + " " + fileResource.type()); + } else if (entry.isGitHubRepository()) { + var repoResource = entry.asGitHubRepository(); + System.out.println(repoResource.id() + " " + repoResource.type()); + } +} + +// Detach a resource +client.beta().sessions().resources().delete(resource.id(), ResourceDeleteParams.builder() + .sessionId(session.id()) + .build()); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Java in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-java` repository for the file list/download bindings. + +--- + +## Session Management + +```java +// List environments +var environments = client.beta().environments().list(); + +// Retrieve a specific environment +var env = client.beta().environments().retrieve(environment.id()); + +// Archive an environment (read-only, existing sessions continue) +client.beta().environments().archive(environment.id()); + +// Delete an environment (only if no sessions reference it) +client.beta().environments().delete(environment.id()); + +// Delete a session +client.beta().sessions().delete(session.id()); +``` + +--- + +## MCP Server Integration + +```java +import com.anthropic.models.beta.agents.BetaManagedAgentsMcpToolsetParams; +import com.anthropic.models.beta.agents.BetaManagedAgentsUrlmcpServerParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +var agent = client.beta().agents().create(AgentCreateParams.builder() + .name("GitHub Assistant") + .model("claude-opus-4-6") + .addMcpServer(BetaManagedAgentsUrlmcpServerParams.builder() + .type(BetaManagedAgentsUrlmcpServerParams.Type.URL) + .name("github") + .url("https://api.githubcopilot.com/mcp/") + .build()) + .addTool(BetaManagedAgentsAgentToolset20260401Params.builder() + .type(BetaManagedAgentsAgentToolset20260401Params.Type.AGENT_TOOLSET_20260401) + .build()) + .addTool(BetaManagedAgentsMcpToolsetParams.builder() + .type(BetaManagedAgentsMcpToolsetParams.Type.MCP_TOOLSET) + .mcpServerName("github") + .build()) + .build()); + +// Session attaches vault(s) containing credentials for those MCP server URLs +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(BetaManagedAgentsAgentParams.builder() + .type(BetaManagedAgentsAgentParams.Type.AGENT) + .id(agent.id()) + .version(agent.version()) + .build()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .build()); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```java +import com.anthropic.core.JsonValue; +import com.anthropic.models.beta.vaults.VaultCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthCreateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthRefreshUpdateParams; +import com.anthropic.models.beta.vaults.credentials.BetaManagedAgentsMcpOAuthUpdateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialCreateParams; +import com.anthropic.models.beta.vaults.credentials.CredentialUpdateParams; +import java.time.OffsetDateTime; + +// Create a vault +var vault = client.beta().vaults().create(VaultCreateParams.builder() + .displayName("Alice") + .metadata(VaultCreateParams.Metadata.builder() + .putAdditionalProperty("external_user_id", JsonValue.from("usr_abc123")) + .build()) + .build()); +System.out.println(vault.id()); // "vlt_01ABC..." + +// Add an OAuth credential +var credential = client.beta().vaults().credentials().create(vault.id(), + CredentialCreateParams.builder() + .displayName("Alice's Slack") + .auth(BetaManagedAgentsMcpOAuthCreateParams.builder() + .type(BetaManagedAgentsMcpOAuthCreateParams.Type.MCP_OAUTH) + .mcpServerUrl("https://mcp.slack.com/mcp") + .accessToken("xoxp-...") + .expiresAt(OffsetDateTime.parse("2026-04-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshParams.builder() + .tokenEndpoint("https://slack.com/api/oauth.v2.access") + .clientId("1234567890.0987654321") + .scope("channels:read chat:write") + .refreshToken("xoxe-1-...") + .clientSecretPostTokenEndpointAuth("abc123...") + .build()) + .build()) + .build()); + +// Rotate the credential (e.g., after a token refresh) +client.beta().vaults().credentials().update(credential.id(), + CredentialUpdateParams.builder() + .vaultId(vault.id()) + .auth(BetaManagedAgentsMcpOAuthUpdateParams.builder() + .type(BetaManagedAgentsMcpOAuthUpdateParams.Type.MCP_OAUTH) + .accessToken("xoxp-new-...") + .expiresAt(OffsetDateTime.parse("2026-05-15T00:00:00Z")) + .refresh(BetaManagedAgentsMcpOAuthRefreshUpdateParams.builder() + .refreshToken("xoxe-1-new-...") + .build()) + .build()) + .build()); + +// Archive a vault +client.beta().vaults().archive(vault.id()); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```java +import com.anthropic.models.beta.sessions.BetaManagedAgentsGitHubRepositoryResourceParams; + +var session = client.beta().sessions().create(SessionCreateParams.builder() + .agent(agent.id()) + .environmentId(environment.id()) + .addVaultId(vault.id()) + .addResource(BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/repo") + .mountPath("/workspace/repo") + .authorizationToken("ghp_your_github_token") + .build()) + .build()); +``` + +Multiple repositories on the same session: + +```java +import java.util.List; + +var resources = List.of( + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/frontend") + .mountPath("/workspace/frontend") + .authorizationToken("ghp_your_github_token") + .build(), + BetaManagedAgentsGitHubRepositoryResourceParams.builder() + .type(BetaManagedAgentsGitHubRepositoryResourceParams.Type.GITHUB_REPOSITORY) + .url("https://github.com/org/backend") + .mountPath("/workspace/backend") + .authorizationToken("ghp_your_github_token") + .build()); +``` + +Rotating a repository's authorization token: + +```java +import com.anthropic.models.beta.sessions.resources.ResourceUpdateParams; + +var listed = client.beta().sessions().resources().list(session.id()); +var repoResourceId = listed.data().get(0).asGitHubRepository().id(); + +client.beta().sessions().resources().update(repoResourceId, ResourceUpdateParams.builder() + .sessionId(session.id()) + .authorizationToken("ghp_your_new_github_token") + .build()); +``` diff --git a/junie/versions/2285.4/skills/claude-api/php/claude-api.md b/junie/versions/2285.4/skills/claude-api/php/claude-api.md new file mode 100644 index 0000000..cec5ead --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/php/claude-api.md @@ -0,0 +1,375 @@ +# Claude API — PHP + +> **Note:** The PHP SDK is the official Anthropic SDK for PHP. A beta tool runner is available via `$client->beta->messages->toolRunner()`. Structured output helpers are supported via `StructuredOutputModel` classes. Agent SDK is not available. Bedrock, Vertex AI, and Foundry clients are supported. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Using API key from environment variable +$client = new Client(apiKey: getenv("ANTHROPIC_API_KEY")); +``` + +### Amazon Bedrock + +```php +use Anthropic\Bedrock; + +// Constructor is private — use the static factory. Reads AWS credentials from env. +$client = Bedrock\Client::fromEnvironment(region: 'us-east-1'); +``` + +### Google Vertex AI + +```php +use Anthropic\Vertex; + +// Constructor is private. Parameter is `location`, not `region`. +$client = Vertex\Client::fromEnvironment( + location: 'us-east5', + projectId: 'my-project-id', +); +``` + +### Anthropic Foundry + +```php +use Anthropic\Foundry; + +// Constructor is private. baseUrl or resource is required. +$client = Foundry\Client::withCredentials( + authToken: getenv('ANTHROPIC_FOUNDRY_AUTH_TOKEN'), + baseUrl: 'https://.services.ai.azure.com/anthropic', +); +``` + +--- + +## Basic Message Request + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [ + ['role' => 'user', 'content' => 'What is the capital of France?'], + ], +); + +// content is an array of polymorphic blocks (TextBlock, ToolUseBlock, +// ThinkingBlock). Accessing ->text on content[0] without checking the block +// type will throw if the first block is not a TextBlock (e.g., when extended +// thinking is enabled and a ThinkingBlock comes first). Always guard: +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +If you only want the first text block: + +```php +foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + break; + } +} +``` + +--- + +## Streaming + +> **Requires SDK v0.5.0+.** v0.4.0 and earlier used a single `$params` array; calling with named parameters throws `Unknown named parameter $model`. Upgrade: `composer require "anthropic-ai/sdk:^0.7"` + +```php +use Anthropic\Messages\RawContentBlockDeltaEvent; +use Anthropic\Messages\TextDelta; + +$stream = $client->messages->createStream( + model: 'claude-opus-4-6', + maxTokens: 64000, + messages: [ + ['role' => 'user', 'content' => 'Write a haiku'], + ], +); + +foreach ($stream as $event) { + if ($event instanceof RawContentBlockDeltaEvent && $event->delta instanceof TextDelta) { + echo $event->delta->text; + } +} +``` + +--- + +## Tool Use + +### Tool Runner (Beta) + +**Beta:** The PHP SDK provides a tool runner via `$client->beta->messages->toolRunner()`. Define tools with `BetaRunnableTool` — a definition array plus a `run` closure: + +```php +use Anthropic\Lib\Tools\BetaRunnableTool; + +$weatherTool = new BetaRunnableTool( + definition: [ + 'name' => 'get_weather', + 'description' => 'Get the current weather for a location.', + 'input_schema' => [ + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], + run: function (array $input): string { + return "The weather in {$input['location']} is sunny and 72°F."; + }, +); + +$runner = $client->beta->messages->toolRunner( + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']], + model: 'claude-opus-4-6', + tools: [$weatherTool], +); + +foreach ($runner as $message) { + foreach ($message->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } + } +} +``` + +### Manual Loop + +Tools are passed as arrays. **The SDK uses camelCase keys** (`inputSchema`, `toolUseID`, `stopReason`) and auto-maps to the API's snake_case on the wire — since v0.5.0. See [shared tool use concepts](../shared/tool-use-concepts.md) for the loop pattern. + +```php +use Anthropic\Messages\ToolUseBlock; + +$tools = [ + [ + 'name' => 'get_weather', + 'description' => 'Get the current weather in a given location', + 'inputSchema' => [ // camelCase, not input_schema + 'type' => 'object', + 'properties' => [ + 'location' => ['type' => 'string', 'description' => 'City and state'], + ], + 'required' => ['location'], + ], + ], +]; + +$messages = [['role' => 'user', 'content' => 'What is the weather in SF?']]; + +$response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, +); + +while ($response->stopReason === 'tool_use') { // camelCase property + $toolResults = []; + foreach ($response->content as $block) { + if ($block instanceof ToolUseBlock) { + // $block->name : string — tool name to dispatch on + // $block->input : array — parsed JSON input + // $block->id : string — pass back as toolUseID + $result = executeYourTool($block->name, $block->input); + $toolResults[] = [ + 'type' => 'tool_result', + 'toolUseID' => $block->id, // camelCase, not tool_use_id + 'content' => $result, + ]; + } + } + + // Append assistant turn + user turn with tool results + $messages[] = ['role' => 'assistant', 'content' => $response->content]; + $messages[] = ['role' => 'user', 'content' => $toolResults]; + + $response = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + tools: $tools, + messages: $messages, + ); +} + +// Final text response +foreach ($response->content as $block) { + if ($block->type === 'text') { + echo $block->text; + } +} +``` + +`$block->type === 'tool_use'` also works; `instanceof ToolUseBlock` narrows for PHPStan. + + +--- + +## Extended Thinking + +**Adaptive thinking is the recommended mode for Claude 4.6+ models.** Claude decides dynamically when and how much to think. + +```php +use Anthropic\Messages\ThinkingBlock; + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + thinking: ['type' => 'adaptive'], + messages: [ + ['role' => 'user', 'content' => 'Solve: 27 * 453'], + ], +); + +// ThinkingBlock(s) precede TextBlock in content +foreach ($message->content as $block) { + if ($block instanceof ThinkingBlock) { + echo "Thinking:\n{$block->thinking}\n\n"; + // $block->signature is an opaque string — preserve verbatim if + // passing thinking blocks back in multi-turn conversations + } elseif ($block->type === 'text') { + echo "Answer: {$block->text}\n"; + } +} +``` + +> **Deprecated:** `['type' => 'enabled', 'budgetTokens' => N]` (fixed-budget extended thinking) still works on Claude 4.6 but is deprecated. Use adaptive thinking above. + +`$block->type === 'thinking'` also works for the check; `instanceof` narrows for PHPStan. + +--- + +## Prompt Caching + +`system:` takes an array of text blocks; set `cacheControl` on the last block. Array-shape syntax (camelCase keys) is idiomatic. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + system: [ + ['type' => 'text', 'text' => $longSystemPrompt, 'cacheControl' => ['type' => 'ephemeral']], + ], + messages: [['role' => 'user', 'content' => 'Summarize the key points']], +); +``` + +For 1-hour TTL: `'cacheControl' => ['type' => 'ephemeral', 'ttl' => '1h']`. There's also a top-level `cacheControl:` on `messages->create(...)` that auto-places on the last cacheable block. + +Verify hits via `$message->usage->cacheCreationInputTokens` / `$message->usage->cacheReadInputTokens`. + +--- + +## Structured Outputs + +### Using StructuredOutputModel (Recommended) + +Define a PHP class implementing `StructuredOutputModel` and pass it as `outputConfig`: + +```php +use Anthropic\Lib\Contracts\StructuredOutputModel; +use Anthropic\Lib\Concerns\StructuredOutputModelTrait; +use Anthropic\Lib\Attributes\Constrained; + +class Person implements StructuredOutputModel +{ + use StructuredOutputModelTrait; + + #[Constrained(description: 'Full name')] + public string $name; + + public int $age; + + public ?string $email = null; // nullable = optional field +} + +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Generate a profile for Alice, age 30']], + outputConfig: ['format' => Person::class], +); + +$person = $message->parsedOutput(); // Person instance +echo $person->name; +``` + +Types are inferred from PHP type hints. Use `#[Constrained(description: '...')]` to add descriptions. Nullable properties (`?string`) become optional fields. + +### Raw Schema + +```php +$message = $client->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + messages: [['role' => 'user', 'content' => 'Extract: John (john@co.com), Enterprise plan']], + outputConfig: [ + 'format' => [ + 'type' => 'json_schema', + 'schema' => [ + 'type' => 'object', + 'properties' => [ + 'name' => ['type' => 'string'], + 'email' => ['type' => 'string'], + 'plan' => ['type' => 'string'], + ], + 'required' => ['name', 'email', 'plan'], + 'additionalProperties' => false, + ], + ], + ], +); + +// First text block contains valid JSON +foreach ($message->content as $block) { + if ($block->type === 'text') { + $data = json_decode($block->text, true); + break; + } +} +``` + +--- + +## Beta Features & Server-Side Tools + +**`betas:` is NOT a param on `$client->messages->create()`** — it only exists on the beta namespace. Use it for features that need an explicit opt-in header: + +```php +use Anthropic\Beta\Messages\BetaRequestMCPServerURLDefinition; + +$response = $client->beta->messages->create( + model: 'claude-opus-4-6', + maxTokens: 16000, + mcpServers: [ + BetaRequestMCPServerURLDefinition::with( + name: 'my-server', + url: 'https://example.com/mcp', + ), + ], + betas: ['mcp-client-2025-11-20'], // only valid on ->beta->messages + messages: [['role' => 'user', 'content' => 'Use the MCP tools']], +); +``` + +**Server-side tools** (bash, web_search, text_editor, code_execution) are GA and work on both paths — `Anthropic\Messages\ToolBash20250124` / `WebSearchTool20260209` / `ToolTextEditor20250728` / `CodeExecutionTool20260120` for non-beta, `Anthropic\Beta\Messages\BetaToolBash20250124` / `BetaWebSearchTool20260209` / `BetaToolTextEditor20250728` / `BetaCodeExecutionTool20260120` for beta. No `betas:` header needed for these. diff --git a/junie/versions/2285.4/skills/claude-api/php/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/php/managed-agents/README.md new file mode 100644 index 0000000..1c8673c --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/php/managed-agents/README.md @@ -0,0 +1,435 @@ +# Managed Agents — PHP + +> **Bindings not shown here:** This README covers the most common managed-agents flows for PHP. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the PHP SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `$client->beta->agents->create` and pass it to every subsequent `->sessions->create`; do not call `agents->create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +composer require "anthropic-ai/sdk" +``` + +## Client Initialization + +```php +use Anthropic\Client; + +// Default (uses ANTHROPIC_API_KEY env var) +$client = new Client(); + +// Explicit API key +$client = new Client(apiKey: 'your-api-key'); +``` + +--- + +## Create an Environment + +```php +$environment = $client->beta->environments->create( + name: 'my-dev-env', + config: ['type' => 'cloud', 'networking' => ['type' => 'unrestricted']], +); +echo "Environment ID: {$environment->id}\n"; // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `$client->beta->agents->create()` — the session takes either `agent: $agent->id` or the typed `BetaManagedAgentsAgentParams::with(type: 'agent', id: $agent->id, version: $agent->version)`. + +### Minimal + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; + +// 1. Create the agent (reusable, versioned) +$agent = $client->beta->agents->create( + name: 'Coding Assistant', + model: 'claude-opus-4-6', + system: 'You are a helpful coding assistant.', + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with( + type: 'agent_toolset_20260401', + ), + ], +); + +// 2. Start a session +$session = $client->beta->sessions->create( + agent: ['type' => 'agent', 'id' => $agent->id, 'version' => $agent->version], + environmentID: $environment->id, + title: 'Quickstart session', +); +echo "Session ID: {$session->id}\n"; +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```php +$updatedAgent = $client->beta->agents->update( + $agent->id, + version: $agent->version, + system: 'You are a helpful coding agent. Always write tests.', +); +echo "New version: {$updatedAgent->version}\n"; + +// List all versions +foreach ($client->beta->agents->versions->list($agent->id)->pagingEachItem() as $version) { + echo "Version {$version->version}: {$version->updatedAt->format(DateTimeInterface::ATOM)}\n"; +} + +// Archive the agent +$archived = $client->beta->agents->archive($agent->id); +echo "Archived at: {$archived->archivedAt->format(DateTimeInterface::ATOM)}\n"; +``` + +--- + +## Send a User Message + +```php +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Review the auth module']], + ], + ], +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +> ℹ️ **Streaming transporter:** PHP's default buffered PSR-18 client never returns for the open-ended session event stream. Use a streaming Guzzle transporter for `streamStream()` calls — other calls keep the default client. + +```php +$streamingClient = new GuzzleHttp\Client(['stream' => true]); + +// Open the stream first, then send the user message +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); +$client->beta->sessions->events->send( + $session->id, + events: [ + [ + 'type' => 'user.message', + 'content' => [['type' => 'text', 'text' => 'Summarize the repo README']], + ], + ], +); + +foreach ($stream as $event) { + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + 'agent.tool_use' => print("\n[Using tool: {$event->name}]\n"), + 'session.error' => printf("\n[Error: %s]", $event->error?->message ?? 'unknown'), + default => null, + }; + if ($event->type === 'session.status_idle' || $event->type === 'session.error') { + break; + } +} +$stream->close(); +``` + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```php +$stream = $client->beta->sessions->events->streamStream( + $session->id, + requestOptions: ['transporter' => $streamingClient], +); + +// Stream is open and buffering. List history before tailing live. +$seenEventIds = []; +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + $seenEventIds[$event->id] = true; +} + +// Tail live events, skipping anything already seen +foreach ($stream as $event) { + if (isset($seenEventIds[$event->id])) { + continue; + } + $seenEventIds[$event->id] = true; + match ($event->type) { + 'agent.message' => array_walk( + $event->content, + static fn($block) => $block->type === 'text' ? print($block->text) : null, + ), + default => null, + }; + if ($event->type === 'session.status_idle') { + break; + } +} +$stream->close(); +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The PHP managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic-ai/sdk` PHP repository for the corresponding params. + +--- + +## Poll Events + +```php +foreach ($client->beta->sessions->events->list($session->id)->pagingEachItem() as $event) { + echo "{$event->type}: {$event->id}\n"; +} +``` + +--- + +## Upload a File + +> ℹ️ **PHP file upload:** The PHP SDK's beta managed-agents file upload binding is not shown in the apps source examples; the canonical PHP example uses raw cURL against `POST /v1/files`. If your codebase prefers the SDK, WebFetch the `anthropic-ai/sdk` PHP repository for the latest binding before writing code. + +```php +use Anthropic\Beta\Sessions\BetaManagedAgentsFileResourceParams; + +// Raw cURL upload (canonical example from the apps source) +$csvPath = 'data.csv'; +$ch = curl_init('https://api.anthropic.com/v1/files'); +curl_setopt_array($ch, [ + CURLOPT_RETURNTRANSFER => true, + CURLOPT_POST => true, + CURLOPT_HTTPHEADER => [ + 'x-api-key: ' . getenv('ANTHROPIC_API_KEY'), + 'anthropic-version: 2023-06-01', + 'anthropic-beta: files-api-2025-04-14', + ], + CURLOPT_POSTFIELDS => ['file' => new CURLFile($csvPath, 'text/csv', 'data.csv')], +]); +$file = json_decode(curl_exec($ch)); +echo "File ID: {$file->id}\n"; + +// Mount in a session +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + resources: [ + BetaManagedAgentsFileResourceParams::with( + type: 'file', + fileID: $file->id, + mountPath: '/workspace/data.csv', + ), + ], +); +``` + +### Add and Manage Resources on an Existing Session + +```php +// Attach an additional file to an open session +$resource = $client->beta->sessions->resources->add( + $session->id, + type: 'file', + fileID: $file->id, +); +echo "{$resource->id}\n"; // "sesrsc_01ABC..." + +// List resources on the session +$listed = $client->beta->sessions->resources->list($session->id); +foreach ($listed->data as $entry) { + echo "{$entry->id} {$entry->type}\n"; +} + +// Detach a resource +$client->beta->sessions->resources->delete($resource->id, sessionID: $session->id); +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for PHP in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic-ai/sdk` PHP repository for the file list/download bindings. + +--- + +## Session Management + +```php +// List environments +$environments = $client->beta->environments->list(); + +// Retrieve a specific environment +$env = $client->beta->environments->retrieve($environment->id); + +// Archive an environment (read-only, existing sessions continue) +$client->beta->environments->archive($environment->id); + +// Delete an environment (only if no sessions reference it) +$client->beta->environments->delete($environment->id); + +// Delete a session +$client->beta->sessions->delete($session->id); +``` + +--- + +## MCP Server Integration + +```php +use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params; +use Anthropic\Beta\Agents\BetaManagedAgentsMCPToolsetParams; +use Anthropic\Beta\Agents\BetaManagedAgentsUrlmcpServerParams; +use Anthropic\Beta\Sessions\BetaManagedAgentsAgentParams; + +// Agent declares MCP server (no auth here — auth goes in a vault) +$agent = $client->beta->agents->create( + name: 'GitHub Assistant', + model: 'claude-opus-4-6', + mcpServers: [ + BetaManagedAgentsUrlmcpServerParams::with( + type: 'url', + name: 'github', + url: 'https://api.githubcopilot.com/mcp/', + ), + ], + tools: [ + BetaManagedAgentsAgentToolset20260401Params::with(type: 'agent_toolset_20260401'), + BetaManagedAgentsMCPToolsetParams::with( + type: 'mcp_toolset', + mcpServerName: 'github', + ), + ], +); + +// Session attaches vault(s) containing credentials for those MCP server URLs +$session = $client->beta->sessions->create( + agent: BetaManagedAgentsAgentParams::with( + type: 'agent', + id: $agent->id, + version: $agent->version, + ), + environmentID: $environment->id, + vaultIDs: [$vault->id], +); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```php +// Create a vault +$vault = $client->beta->vaults->create( + displayName: 'Alice', + metadata: ['external_user_id' => 'usr_abc123'], +); +echo $vault->id . "\n"; // "vlt_01ABC..." + +// Add an OAuth credential +$credential = $client->beta->vaults->credentials->create( + vaultID: $vault->id, + displayName: "Alice's Slack", + auth: [ + 'type' => 'mcp_oauth', + 'mcp_server_url' => 'https://mcp.slack.com/mcp', + 'access_token' => 'xoxp-...', + 'expires_at' => '2026-04-15T00:00:00Z', + 'refresh' => [ + 'token_endpoint' => 'https://slack.com/api/oauth.v2.access', + 'client_id' => '1234567890.0987654321', + 'scope' => 'channels:read chat:write', + 'refresh_token' => 'xoxe-1-...', + 'token_endpoint_auth' => [ + 'type' => 'client_secret_post', + 'client_secret' => 'abc123...', + ], + ], + ], +); + +// Rotate the credential (e.g., after a token refresh) +$client->beta->vaults->credentials->update( + $credential->id, + vaultID: $vault->id, + auth: [ + 'type' => 'mcp_oauth', + 'access_token' => 'xoxp-new-...', + 'expires_at' => '2026-05-15T00:00:00Z', + 'refresh' => ['refresh_token' => 'xoxe-1-new-...'], + ], +); + +// Archive a vault +$client->beta->vaults->archive($vault->id); +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```php +$session = $client->beta->sessions->create( + agent: $agent->id, + environmentID: $environment->id, + vaultIDs: [$vault->id], + resources: [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/repo', + 'mountPath' => '/workspace/repo', + 'authorizationToken' => 'ghp_your_github_token', + ], + ], +); +``` + +Multiple repositories on the same session: + +```php +$resources = [ + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/frontend', + 'mountPath' => '/workspace/frontend', + 'authorizationToken' => 'ghp_your_github_token', + ], + [ + 'type' => 'github_repository', + 'url' => 'https://github.com/org/backend', + 'mountPath' => '/workspace/backend', + 'authorizationToken' => 'ghp_your_github_token', + ], +]; +``` + +Rotating a repository's authorization token: + +```php +$listed = $client->beta->sessions->resources->list($session->id); +$repoResourceId = $listed->data[0]->id; + +$client->beta->sessions->resources->update( + $repoResourceId, + sessionID: $session->id, + authorizationToken: 'ghp_your_new_github_token', +); +``` diff --git a/junie/versions/2285.4/skills/claude-api/python/claude-api/README.md b/junie/versions/2285.4/skills/claude-api/python/claude-api/README.md new file mode 100644 index 0000000..c2acc35 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/claude-api/README.md @@ -0,0 +1,420 @@ +# Claude API — Python + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") + +# Async client +async_client = anthropic.AsyncAnthropic() +``` + +--- + +## Basic Message Request + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[ + {"role": "user", "content": "What is the capital of France?"} + ] +) +# response.content is a list of content block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). Check .type before accessing .text. +for block in response.content: + if block.type == "text": + print(block.text) +``` + +--- + +## System Prompts + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system="You are a helpful coding assistant. Always provide examples in Python.", + messages=[{"role": "user", "content": "How do I read a JSON file?"}] +) +``` + +--- + +## Vision (Images) + +### Base64 + +```python +import base64 + +with open("image.png", "rb") as f: + image_data = base64.standard_b64encode(f.read()).decode("utf-8") + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "base64", + "media_type": "image/png", + "data": image_data + } + }, + {"type": "text", "text": "What's in this image?"} + ] + }] +) +``` + +### URL + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + { + "type": "image", + "source": { + "type": "url", + "url": "https://example.com/image.png" + } + }, + {"type": "text", "text": "Describe this image"} + ] + }] +) +``` + +--- + +## Prompt Caching + +Cache large context to reduce costs (up to 90% savings). **Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request — no need to annotate individual content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, # auto-caches the last cacheable block + system="You are an expert on this large document...", + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral"} # default TTL is 5 minutes + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# With explicit TTL (time-to-live) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + system=[{ + "type": "text", + "text": "You are an expert on this large document...", + "cache_control": {"type": "ephemeral", "ttl": "1h"} # 1 hour TTL + }], + messages=[{"role": "user", "content": "Summarize the key points"}] +) +``` + +### Verifying Cache Hits + +```python +print(response.usage.cache_creation_input_tokens) # tokens written to cache (~1.25x cost) +print(response.usage.cache_read_input_tokens) # tokens served from cache (~0.1x cost) +print(response.usage.input_tokens) # uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `datetime.now()` or a UUID in the system prompt, unsorted `json.dumps()`, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```python +# Opus 4.6: adaptive thinking (recommended) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + thinking={"type": "adaptive"}, + output_config={"effort": "high"}, # low | medium | high | max + messages=[{"role": "user", "content": "Solve this step by step..."}] +) + +# Access thinking and response +for block in response.content: + if block.type == "thinking": + print(f"Thinking: {block.thinking}") + elif block.type == "text": + print(f"Response: {block.text}") +``` + +--- + +## Error Handling + +```python +import anthropic + +try: + response = client.messages.create(...) +except anthropic.BadRequestError as e: + print(f"Bad request: {e.message}") +except anthropic.AuthenticationError: + print("Invalid API key") +except anthropic.PermissionDeniedError: + print("API key lacks required permissions") +except anthropic.NotFoundError: + print("Invalid model or endpoint") +except anthropic.RateLimitError as e: + retry_after = int(e.response.headers.get("retry-after", "60")) + print(f"Rate limited. Retry after {retry_after}s.") +except anthropic.APIStatusError as e: + if e.status_code >= 500: + print(f"Server error ({e.status_code}). Retry later.") + else: + print(f"API error: {e.message}") +except anthropic.APIConnectionError: + print("Network error. Check internet connection.") +``` + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. + +```python +class ConversationManager: + """Manage multi-turn conversations with the Claude API.""" + + def __init__(self, client: anthropic.Anthropic, model: str, system: str = None): + self.client = client + self.model = model + self.system = system + self.messages = [] + + def send(self, user_message: str, **kwargs) -> str: + """Send a message and get a response.""" + self.messages.append({"role": "user", "content": user_message}) + + response = self.client.messages.create( + model=self.model, + max_tokens=kwargs.get("max_tokens", 16000), + system=self.system, + messages=self.messages, + **kwargs + ) + + assistant_message = next( + (b.text for b in response.content if b.type == "text"), "" + ) + self.messages.append({"role": "assistant", "content": assistant_message}) + + return assistant_message + +# Usage +conversation = ConversationManager( + client=anthropic.Anthropic(), + model="claude-opus-4-6", + system="You are a helpful assistant." +) + +response1 = conversation.send("My name is Alice.") +response2 = conversation.send("What's my name?") # Claude remembers "Alice" +``` + +**Rules:** + +- Messages must alternate between `user` and `assistant` +- First message must be `user` + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```python +import anthropic + +client = anthropic.Anthropic() +messages = [] + +def chat(user_message: str) -> str: + messages.append({"role": "user", "content": user_message}) + + response = client.beta.messages.create( + betas=["compact-2026-01-12"], + model="claude-opus-4-6", + max_tokens=16000, + messages=messages, + context_management={ + "edits": [{"type": "compact_20260112"}] + } + ) + + # Append full content — compaction blocks must be preserved + messages.append({"role": "assistant", "content": response.content}) + + return next(block.text for block in response.content if block.type == "text") + +# Compaction triggers automatically when context grows large +print(chat("Help me build a Python web scraper")) +print(chat("Add support for JavaScript-rendered pages")) +print(chat("Now add rate limiting and error handling")) +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +|-------|---------| +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match your schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```python +# Automatic caching (simplest — caches the last cacheable block) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + cache_control={"type": "ephemeral"}, + system=large_document_text, # e.g., 50KB of context + messages=[{"role": "user", "content": "Summarize the key points"}] +) + +# First request: full cost +# Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Choose the Right Model + +```python +# Default to Opus for most tasks +response = client.messages.create( + model="claude-opus-4-6", # $5.00/$25.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing"}] +) + +# Use Sonnet for high-volume production workloads +standard_response = client.messages.create( + model="claude-sonnet-4-6", # $3.00/$15.00 per 1M tokens + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize this document"}] +) + +# Use Haiku only for simple, speed-critical tasks +simple_response = client.messages.create( + model="claude-haiku-4-5", # $1.00/$5.00 per 1M tokens + max_tokens=256, + messages=[{"role": "user", "content": "Classify this as positive or negative"}] +) +``` + +### 3. Use Token Counting Before Requests + +```python +count_response = client.messages.count_tokens( + model="claude-opus-4-6", + messages=messages, + system=system +) + +estimated_input_cost = count_response.input_tokens * 0.000005 # $5/1M tokens +print(f"Estimated input cost: ${estimated_input_cost:.4f}") +``` + +--- + +## Retry with Exponential Backoff + +> **Note:** The Anthropic SDK automatically retries rate limit (429) and server errors (5xx) with exponential backoff. You can configure this with `max_retries` (default: 2). Only implement custom retry logic if you need behavior beyond what the SDK provides. + +```python +import time +import random +import anthropic + +def call_with_retry( + client: anthropic.Anthropic, + max_retries: int = 5, + base_delay: float = 1.0, + max_delay: float = 60.0, + **kwargs +): + """Call the API with exponential backoff retry.""" + last_exception = None + + for attempt in range(max_retries): + try: + return client.messages.create(**kwargs) + except anthropic.RateLimitError as e: + last_exception = e + except anthropic.APIStatusError as e: + if e.status_code >= 500: + last_exception = e + else: + raise # Client errors (4xx except 429) should not be retried + + delay = min(base_delay * (2 ** attempt) + random.uniform(0, 1), max_delay) + print(f"Retry {attempt + 1}/{max_retries} after {delay:.1f}s") + time.sleep(delay) + + raise last_exception +``` diff --git a/junie/versions/2285.4/skills/claude-api/python/claude-api/batches.md b/junie/versions/2285.4/skills/claude-api/python/claude-api/batches.md new file mode 100644 index 0000000..bed5401 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/claude-api/batches.md @@ -0,0 +1,185 @@ +# Message Batches API — Python + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```python +import anthropic +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id="request-1", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Summarize climate change impacts"}] + ) + ), + Request( + custom_id="request-2", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Explain quantum computing basics"}] + ) + ), + ] +) + +print(f"Batch ID: {message_batch.id}") +print(f"Status: {message_batch.processing_status}") +``` + +--- + +## Poll for Completion + +```python +import time + +while True: + batch = client.messages.batches.retrieve(message_batch.id) + if batch.processing_status == "ended": + break + print(f"Status: {batch.processing_status}, processing: {batch.request_counts.processing}") + time.sleep(60) + +print("Batch complete!") +print(f"Succeeded: {batch.request_counts.succeeded}") +print(f"Errored: {batch.request_counts.errored}") +``` + +--- + +## Retrieve Results + +> **Note:** Examples below use `match/case` syntax, requiring Python 3.10+. For earlier versions, use `if/elif` chains instead. + +```python +for result in client.messages.batches.results(message_batch.id): + match result.result.type: + case "succeeded": + msg = result.result.message + text = next((b.text for b in msg.content if b.type == "text"), "") + print(f"[{result.custom_id}] {text[:100]}") + case "errored": + if result.result.error.type == "invalid_request": + print(f"[{result.custom_id}] Validation error - fix request and retry") + else: + print(f"[{result.custom_id}] Server error - safe to retry") + case "canceled": + print(f"[{result.custom_id}] Canceled") + case "expired": + print(f"[{result.custom_id}] Expired - resubmit") +``` + +--- + +## Cancel a Batch + +```python +cancelled = client.messages.batches.cancel(message_batch.id) +print(f"Status: {cancelled.processing_status}") # "canceling" +``` + +--- + +## Batch with Prompt Caching + +```python +shared_system = [ + {"type": "text", "text": "You are a literary analyst."}, + { + "type": "text", + "text": large_document_text, # Shared across all requests + "cache_control": {"type": "ephemeral"} + } +] + +message_batch = client.messages.batches.create( + requests=[ + Request( + custom_id=f"analysis-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-opus-4-6", + max_tokens=16000, + system=shared_system, + messages=[{"role": "user", "content": question}] + ) + ) + for i, question in enumerate(questions) + ] +) +``` + +--- + +## Full End-to-End Example + +```python +import anthropic +import time +from anthropic.types.message_create_params import MessageCreateParamsNonStreaming +from anthropic.types.messages.batch_create_params import Request + +client = anthropic.Anthropic() + +# 1. Prepare requests +items_to_classify = [ + "The product quality is excellent!", + "Terrible customer service, never again.", + "It's okay, nothing special.", +] + +requests = [ + Request( + custom_id=f"classify-{i}", + params=MessageCreateParamsNonStreaming( + model="claude-haiku-4-5", + max_tokens=50, + messages=[{ + "role": "user", + "content": f"Classify as positive/negative/neutral (one word): {text}" + }] + ) + ) + for i, text in enumerate(items_to_classify) +] + +# 2. Create batch +batch = client.messages.batches.create(requests=requests) +print(f"Created batch: {batch.id}") + +# 3. Wait for completion +while True: + batch = client.messages.batches.retrieve(batch.id) + if batch.processing_status == "ended": + break + time.sleep(10) + +# 4. Collect results +results = {} +for result in client.messages.batches.results(batch.id): + if result.result.type == "succeeded": + msg = result.result.message + results[result.custom_id] = next((b.text for b in msg.content if b.type == "text"), "") + +for custom_id, classification in sorted(results.items()): + print(f"{custom_id}: {classification}") +``` diff --git a/junie/versions/2285.4/skills/claude-api/python/claude-api/files-api.md b/junie/versions/2285.4/skills/claude-api/python/claude-api/files-api.md new file mode 100644 index 0000000..93efef7 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/claude-api/files-api.md @@ -0,0 +1,165 @@ +# Files API — Python + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas=["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```python +import anthropic + +client = anthropic.Anthropic() + +uploaded = client.beta.files.upload( + file=("report.pdf", open("report.pdf", "rb"), "application/pdf"), +) +print(f"File ID: {uploaded.id}") +print(f"Size: {uploaded.size_bytes} bytes") +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```python +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Summarize the key findings in this report."}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id}, + "title": "Q4 Report", # optional + "citations": {"enabled": True} # optional, enables citations + } + ] + }], + betas=["files-api-2025-04-14"], +) +for block in response.content: + if block.type == "text": + print(block.text) +``` + +### Image + +```python +image_file = client.beta.files.upload( + file=("photo.png", open("photo.png", "rb"), "image/png"), +) + +response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "What's in this image?"}, + { + "type": "image", + "source": {"type": "file", "file_id": image_file.id} + } + ] + }], + betas=["files-api-2025-04-14"], +) +``` + +--- + +## Manage Files + +### List Files + +```python +files = client.beta.files.list() +for f in files.data: + print(f"{f.id}: {f.filename} ({f.size_bytes} bytes)") +``` + +### Get File Metadata + +```python +file_info = client.beta.files.retrieve_metadata("file_011CNha8iCJcU1wXNR6q4V8w") +print(f"Filename: {file_info.filename}") +print(f"MIME type: {file_info.mime_type}") +``` + +### Delete a File + +```python +client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w") +``` + +### Download a File + +Only files created by the code execution tool or skills can be downloaded (not user-uploaded files). + +```python +file_content = client.beta.files.download("file_011CNha8iCJcU1wXNR6q4V8w") +file_content.write_to_file("output.txt") +``` + +--- + +## Full End-to-End Example + +Upload a document once, ask multiple questions about it: + +```python +import anthropic + +client = anthropic.Anthropic() + +# 1. Upload once +uploaded = client.beta.files.upload( + file=("contract.pdf", open("contract.pdf", "rb"), "application/pdf"), +) +print(f"Uploaded: {uploaded.id}") + +# 2. Ask multiple questions using the same file_id +questions = [ + "What are the key terms and conditions?", + "What is the termination clause?", + "Summarize the payment schedule.", +] + +for question in questions: + response = client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": question}, + { + "type": "document", + "source": {"type": "file", "file_id": uploaded.id} + } + ] + }], + betas=["files-api-2025-04-14"], + ) + print(f"\nQ: {question}") + text = next((b.text for b in response.content if b.type == "text"), "") + print(f"A: {text[:200]}") + +# 3. Clean up when done +client.beta.files.delete(uploaded.id) +``` diff --git a/junie/versions/2285.4/skills/claude-api/python/claude-api/streaming.md b/junie/versions/2285.4/skills/claude-api/python/claude-api/streaming.md new file mode 100644 index 0000000..b21f9ae --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/claude-api/streaming.md @@ -0,0 +1,162 @@ +# Streaming — Python + +## Quick Start + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +``` + +### Async + +```python +async with async_client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] +) as stream: + async for text in stream.text_stream: + print(text, end="", flush=True) +``` + +--- + +## Handling Different Content Types + +Claude may return text, thinking blocks, or tool use. Handle each appropriately: + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + thinking={"type": "adaptive"}, + messages=[{"role": "user", "content": "Analyze this problem"}] +) as stream: + for event in stream: + if event.type == "content_block_start": + if event.content_block.type == "thinking": + print("\n[Thinking...]") + elif event.content_block.type == "text": + print("\n[Response:]") + + elif event.type == "content_block_delta": + if event.delta.type == "thinking_delta": + print(event.delta.thinking, end="", flush=True) + elif event.delta.type == "text_delta": + print(event.delta.text, end="", flush=True) +``` + +--- + +## Streaming with Tool Use + +The Python tool runner currently returns complete messages. Use streaming for individual API calls within a manual loop if you need per-token streaming with tools: + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + tools=tools, + messages=messages +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + response = stream.get_final_message() + # Continue with tool execution if response.stop_reason == "tool_use" +``` + +--- + +## Getting the Final Message + +```python +with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Hello"}] +) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) + + # Get full message after streaming + final_message = stream.get_final_message() + print(f"\n\nTokens used: {final_message.usage.output_tokens}") +``` + +--- + +## Streaming with Progress Updates + +```python +def stream_with_progress(client, **kwargs): + """Stream a response with progress updates.""" + total_tokens = 0 + content_parts = [] + + with client.messages.stream(**kwargs) as stream: + for event in stream: + if event.type == "content_block_delta": + if event.delta.type == "text_delta": + text = event.delta.text + content_parts.append(text) + print(text, end="", flush=True) + + elif event.type == "message_delta": + if event.usage and event.usage.output_tokens is not None: + total_tokens = event.usage.output_tokens + + final_message = stream.get_final_message() + + print(f"\n\n[Tokens used: {total_tokens}]") + return "".join(content_parts) +``` + +--- + +## Error Handling in Streams + +```python +try: + with client.messages.stream( + model="claude-opus-4-6", + max_tokens=64000, + messages=[{"role": "user", "content": "Write a story"}] + ) as stream: + for text in stream.text_stream: + print(text, end="", flush=True) +except anthropic.APIConnectionError: + print("\nConnection lost. Please retry.") +except anthropic.RateLimitError: + print("\nRate limited. Please wait and retry.") +except anthropic.APIStatusError as e: + print(f"\nAPI error: {e.status_code}") +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `flush=True` to show tokens immediately +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use timeouts** — Set appropriate timeouts for your application +5. **Default to streaming** — Use `.get_final_message()` to get the complete response even when streaming, giving you timeout protection without needing to handle individual events diff --git a/junie/versions/2285.4/skills/claude-api/python/claude-api/tool-use.md b/junie/versions/2285.4/skills/claude-api/python/claude-api/tool-use.md new file mode 100644 index 0000000..52bbe49 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/claude-api/tool-use.md @@ -0,0 +1,590 @@ +# Tool Use — Python + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the Python SDK. + +Use the `@beta_tool` decorator to define tools as typed functions, then pass them to `client.beta.messages.tool_runner()`: + +```python +import anthropic +from anthropic import beta_tool + +client = anthropic.Anthropic() + +@beta_tool +def get_weather(location: str, unit: str = "celsius") -> str: + """Get current weather for a location. + + Args: + location: City and state, e.g., San Francisco, CA. + unit: Temperature unit, either "celsius" or "fahrenheit". + """ + # Your implementation here + return f"72°F and sunny in {location}" + +# The tool runner handles the agentic loop automatically +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[get_weather], + messages=[{"role": "user", "content": "What's the weather in Paris?"}], +) + +# Each iteration yields a BetaMessage; iteration stops when Claude is done +for message in runner: + print(message) +``` + +For async usage, use `@beta_async_tool` with `async def` functions. + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via decorators +- Tool schemas are generated automatically from function signatures +- Iteration stops automatically when Claude has no more tool calls + +--- + +## MCP Tool Conversion Helpers + +**Beta.** Convert [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) tools, prompts, and resources to Anthropic API types for use with the tool runner. Requires `pip install anthropic[mcp]` (Python 3.10+). + +> **Note:** The Claude API also supports an `mcp_servers` parameter that lets Claude connect directly to remote MCP servers. Use these helpers instead when you need local MCP servers, prompts, resources, or more control over the MCP connection. + +### MCP Tools with Tool Runner + +```python +from anthropic import AsyncAnthropic +from anthropic.lib.tools.mcp import async_mcp_tool +from mcp import ClientSession +from mcp.client.stdio import stdio_client, StdioServerParameters + +client = AsyncAnthropic() + +async with stdio_client(StdioServerParameters(command="mcp-server")) as (read, write): + async with ClientSession(read, write) as mcp_client: + await mcp_client.initialize() + + tools_result = await mcp_client.list_tools() + # tool_runner is sync — returns the runner, not a coroutine + runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Use the available tools"}], + tools=[async_mcp_tool(t, mcp_client) for t in tools_result.tools], + ) + async for message in runner: + print(message) +``` + +For sync usage, use `mcp_tool` instead of `async_mcp_tool`. + +### MCP Prompts + +```python +from anthropic.lib.tools.mcp import mcp_message + +prompt = await mcp_client.get_prompt(name="my-prompt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[mcp_message(m) for m in prompt.messages], +) +``` + +### MCP Resources as Content + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_content + +resource = await mcp_client.read_resource(uri="file:///path/to/doc.txt") +response = await client.beta.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": [ + mcp_resource_to_content(resource), + {"type": "text", "text": "Summarize this document"}, + ], + }], +) +``` + +### Upload MCP Resources as Files + +```python +from anthropic.lib.tools.mcp import mcp_resource_to_file + +resource = await mcp_client.read_resource(uri="file:///path/to/data.json") +uploaded = await client.beta.files.upload(file=mcp_resource_to_file(resource)) +``` + +Conversion functions raise `UnsupportedMCPValueError` if an MCP value cannot be converted (e.g., unsupported content types like audio, unsupported MIME types). + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval): + +```python +import anthropic + +client = anthropic.Anthropic() +tools = [...] # Your tool definitions +messages = [{"role": "user", "content": user_input}] + +# Agentic loop: keep going until Claude stops calling tools +while True: + response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=messages + ) + + # If Claude is done (no more tool calls), break + if response.stop_reason == "end_turn": + break + + # Server-side tool hit iteration limit; re-send to continue + if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_input}, + {"role": "assistant", "content": response.content}, + ] + continue + + # Extract tool use blocks from the response + tool_use_blocks = [b for b in response.content if b.type == "tool_use"] + + # Append assistant's response (including tool_use blocks) + messages.append({"role": "assistant", "content": response.content}) + + # Execute each tool and collect results + tool_results = [] + for tool in tool_use_blocks: + result = execute_tool(tool.name, tool.input) # Your implementation + tool_results.append({ + "type": "tool_result", + "tool_use_id": tool.id, # Must match the tool_use block's id + "content": result + }) + + # Append tool results as a user message + messages.append({"role": "user", "content": tool_results}) + +# Final response text +final_text = next(b.text for b in response.content if b.type == "text") +``` + +--- + +## Handling Tool Results + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) + +for block in response.content: + if block.type == "tool_use": + tool_name = block.name + tool_input = block.input + tool_use_id = block.id + + result = execute_tool(tool_name, tool_input) + + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + {"role": "user", "content": "What's the weather in Paris?"}, + {"role": "assistant", "content": response.content}, + { + "role": "user", + "content": [{ + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": result + }] + } + ] + ) +``` + +--- + +## Multiple Tool Calls + +```python +tool_results = [] + +for block in response.content: + if block.type == "tool_use": + result = execute_tool(block.name, block.input) + tool_results.append({ + "type": "tool_result", + "tool_use_id": block.id, + "content": result + }) + +# Send all results back at once +if tool_results: + followup = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + messages=[ + *previous_messages, + {"role": "assistant", "content": response.content}, + {"role": "user", "content": tool_results} + ] + ) +``` + +--- + +## Error Handling in Tool Results + +```python +tool_result = { + "type": "tool_result", + "tool_use_id": tool_use_id, + "content": "Error: Location 'xyz' not found. Please provide a valid city name.", + "is_error": True +} +``` + +--- + +## Tool Choice + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + tools=tools, + tool_choice={"type": "tool", "name": "get_weather"}, # Force specific tool + messages=[{"role": "user", "content": "What's the weather in Paris?"}] +) +``` + +--- + +## Code Execution + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]" + }], + tools=[{ + "type": "code_execution_20260120", + "name": "code_execution" + }] +) + +for block in response.content: + if block.type == "text": + print(block.text) + elif block.type == "bash_code_execution_tool_result": + print(f"stdout: {block.content.stdout}") +``` + +### Upload Files for Analysis + +```python +# 1. Upload a file +uploaded = client.beta.files.upload(file=open("sales_data.csv", "rb")) + +# 2. Pass to code execution via container_upload block +# Code execution is GA; Files API is still beta (pass via extra_headers) +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + extra_headers={"anthropic-beta": "files-api-2025-04-14"}, + messages=[{ + "role": "user", + "content": [ + {"type": "text", "text": "Analyze this sales data. Show trends and create a visualization."}, + {"type": "container_upload", "file_id": uploaded.id} + ] + }], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Retrieve Generated Files + +```python +import os + +OUTPUT_DIR = "./claude_outputs" +os.makedirs(OUTPUT_DIR, exist_ok=True) + +for block in response.content: + if block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result" and result.content: + for file_ref in result.content: + if file_ref.type == "bash_code_execution_output": + metadata = client.beta.files.retrieve_metadata(file_ref.file_id) + file_content = client.beta.files.download(file_ref.file_id) + # Use basename to prevent path traversal; validate result + safe_name = os.path.basename(metadata.filename) + if not safe_name or safe_name in (".", ".."): + print(f"Skipping invalid filename: {metadata.filename}") + continue + output_path = os.path.join(OUTPUT_DIR, safe_name) + file_content.write_to_file(output_path) + print(f"Saved: {output_path}") +``` + +### Container Reuse + +```python +# First request: set up environment +response1 = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Install tabulate and create data.json with sample data"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) + +# Get container ID from response +container_id = response1.container.id + +# Second request: reuse the same container +response2 = client.messages.create( + container=container_id, + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Read data.json and display as a formatted table"}], + tools=[{"type": "code_execution_20260120", "name": "code_execution"}] +) +``` + +### Response Structure + +```python +for block in response.content: + if block.type == "text": + print(block.text) # Claude's explanation + elif block.type == "server_tool_use": + print(f"Running: {block.name} - {block.input}") # What Claude is doing + elif block.type == "bash_code_execution_tool_result": + result = block.content + if result.type == "bash_code_execution_result": + if result.return_code == 0: + print(f"Output: {result.stdout}") + else: + print(f"Error: {result.stderr}") + else: + print(f"Tool error: {result.error_code}") + elif block.type == "text_editor_code_execution_tool_result": + print(f"File operation: {block.content}") +``` + +--- + +## Memory Tool + +### Basic Usage + +```python +import anthropic + +client = anthropic.Anthropic() + +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Remember that my preferred language is Python."}], + tools=[{"type": "memory_20250818", "name": "memory"}], +) +``` + +### SDK Memory Helper + +Subclass `BetaAbstractMemoryTool`: + +```python +from anthropic.lib.tools import BetaAbstractMemoryTool + +class MyMemoryTool(BetaAbstractMemoryTool): + def view(self, command): ... + def create(self, command): ... + def str_replace(self, command): ... + def insert(self, command): ... + def delete(self, command): ... + def rename(self, command): ... + +memory = MyMemoryTool() + +# Use with tool runner +runner = client.beta.messages.tool_runner( + model="claude-opus-4-6", + max_tokens=16000, + tools=[memory], + messages=[{"role": "user", "content": "Remember my preferences"}], +) + +for message in runner: + print(message) +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-python/blob/main/examples/memory/basic.py` + +--- + +## Structured Outputs + +### JSON Outputs (Pydantic — Recommended) + +```python +from pydantic import BaseModel +from typing import List +import anthropic + +class ContactInfo(BaseModel): + name: str + email: str + plan: str + interests: List[str] + demo_requested: bool + +client = anthropic.Anthropic() + +response = client.messages.parse( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo." + }], + output_format=ContactInfo, +) + +# response.parsed_output is a validated ContactInfo instance +contact = response.parsed_output +print(contact.name) # "Jane Doe" +print(contact.interests) # ["API", "SDKs"] +``` + +### Raw Schema + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{ + "role": "user", + "content": "Extract info: John Smith (john@example.com) wants the Enterprise plan." + }], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "name": {"type": "string"}, + "email": {"type": "string"}, + "plan": {"type": "string"}, + "demo_requested": {"type": "boolean"} + }, + "required": ["name", "email", "plan", "demo_requested"], + "additionalProperties": False + } + } + } +) + +import json +# output_config.format guarantees the first block is text with valid JSON +text = next(b.text for b in response.content if b.type == "text") +data = json.loads(text) +``` + +### Strict Tool Use + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Book a flight to Tokyo for 2 passengers on March 15"}], + tools=[{ + "name": "book_flight", + "description": "Book a flight to a destination", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"}, + "passengers": {"type": "integer", "enum": [1, 2, 3, 4, 5, 6, 7, 8]} + }, + "required": ["destination", "date", "passengers"], + "additionalProperties": False + } + }] +) +``` + +### Using Both Together + +```python +response = client.messages.create( + model="claude-opus-4-6", + max_tokens=16000, + messages=[{"role": "user", "content": "Plan a trip to Paris next month"}], + output_config={ + "format": { + "type": "json_schema", + "schema": { + "type": "object", + "properties": { + "summary": {"type": "string"}, + "next_steps": {"type": "array", "items": {"type": "string"}} + }, + "required": ["summary", "next_steps"], + "additionalProperties": False + } + } + }, + tools=[{ + "name": "search_flights", + "description": "Search for available flights", + "strict": True, + "input_schema": { + "type": "object", + "properties": { + "destination": {"type": "string"}, + "date": {"type": "string", "format": "date"} + }, + "required": ["destination", "date"], + "additionalProperties": False + } + }] +) +``` diff --git a/junie/versions/2285.4/skills/claude-api/python/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/python/managed-agents/README.md new file mode 100644 index 0000000..49b6783 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/python/managed-agents/README.md @@ -0,0 +1,329 @@ +# Managed Agents — Python + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Python. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Python SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +pip install anthropic +``` + +## Client Initialization + +```python +import anthropic + +# Default (uses ANTHROPIC_API_KEY env var) +client = anthropic.Anthropic() + +# Explicit API key +client = anthropic.Anthropic(api_key="your-api-key") +``` + +--- + +## Create an Environment + +```python +environment = client.beta.environments.create( + name="my-dev-env", + config={ + "type": "cloud", + "networking": {"type": "unrestricted"}, + }, +) +print(environment.id) # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent={"type": "agent", "id": agent.id}`. + +### Minimal + +```python +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name="Coding Assistant", + model="claude-opus-4-6", + tools=[{"type": "agent_toolset_20260401", "default_config": {"enabled": True}}], +) + +# 2. Start a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, +) +print(session.id, session.status) +``` + +### With system prompt and custom tools + +```python +import os + +agent = client.beta.agents.create( + name="Code Reviewer", + model="claude-opus-4-6", + system="You are a senior code reviewer.", + tools=[ + {"type": "agent_toolset_20260401"}, + { + "type": "custom", + "name": "run_tests", + "description": "Run the test suite", + "input_schema": { + "type": "object", + "properties": { + "test_path": {"type": "string", "description": "Path to test file"} + }, + "required": ["test_path"], + }, + }, + ], +) + +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + title="Code review session", + resources=[ + { + "type": "github_repository", + "url": "https://github.com/owner/repo", + "mount_path": "/workspace/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], + "branch": "main", + } + ], +) +``` + +--- + +## Send a User Message + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.message", + "content": [{"type": "text", "text": "Review the auth module"}], + } + ], +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```python +import json + +# Stream-first: open stream, then send while stream is live +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + client.beta.sessions.events.send( + session_id=session.id, + events=[{"type": "user.message", "content": [{"type": "text", "text": "..."}]}], + ) + for event in stream: + ... # process events + +# Standalone stream iteration: +with client.beta.sessions.stream( + session_id=session.id, +) as stream: + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + # Custom tool invocation — session is now idle + print(f"\nCustom tool call: {event.tool_name}") + print(f"Input: {json.dumps(event.input)}") + # Send result back (see below) + elif event.type == "session.status_idle": + print("\n--- Agent idle ---") + elif event.type == "session.status_terminated": + print("\n--- Session terminated ---") + break +``` + +--- + +## Provide Custom Tool Result + +```python +client.beta.sessions.events.send( + session_id=session.id, + events=[ + { + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{"type": "text", "text": "All 42 tests passed."}], + } + ], +) +``` + +--- + +## Poll Events + +```python +events = client.beta.sessions.events.list( + session_id=session.id, +) +for event in events.data: + print(f"{event.type}: {event.id}") +``` + +> ⚠️ **Prefer the SDK over raw `requests`/`httpx`.** If you hand-roll a poll loop, don't assume `timeout=(5, 60)` or `httpx.Timeout(120)` caps total call duration — both are **per-chunk** read timeouts (reset on every byte), so a trickling response can block forever. For a hard wall-clock deadline, track `time.monotonic()` at the loop level and bail explicitly, or wrap with `asyncio.wait_for()`. See [Receiving Events](../../shared/managed-agents-events.md#receiving-events). + +--- + +## Full Streaming Loop with Custom Tools + +```python +import json + + +def run_custom_tool(tool_name: str, tool_input: dict) -> str: + """Execute a custom tool and return the result.""" + if tool_name == "run_tests": + # Your tool implementation here + return "All tests passed." + return f"Unknown tool: {tool_name}" + + +def run_session(client, session_id: str): + """Stream events and handle custom tool calls.""" + while True: + with client.beta.sessions.stream( + session_id=session_id, + ) as stream: + tool_calls = [] + for event in stream: + if event.type == "agent.message": + for block in event.content: + if block.type == "text": + print(block.text, end="", flush=True) + elif event.type == "agent.custom_tool_use": + tool_calls.append(event) + elif event.type == "session.status_idle": + break + elif event.type == "session.status_terminated": + return + + if not tool_calls: + break + + # Process custom tool calls + results = [] + for call in tool_calls: + result = run_custom_tool(call.tool_name, call.input) + results.append({ + "type": "user.custom_tool_result", + "custom_tool_use_id": call.id, + "content": [{"type": "text", "text": result}], + }) + + client.beta.sessions.events.send( + session_id=session_id, + events=results, + ) +``` + +--- + +## Upload a File + +```python +with open("data.csv", "rb") as f: + file = client.beta.files.upload( + file=f, + ) + +# Use in a session +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment.id, + resources=[{"type": "file", "file_id": file.id, "mount_path": "/workspace/data.csv"}], +) +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```python +# List files associated with a session +files = client.beta.files.list(session_id=session.id) +for f in files.data: + print(f.filename, f.size_bytes) + # Download each file and save to disk + file_content = client.beta.files.download(f.id) + file_content.write_to_file(f.filename) +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list` (with `scope=session_id` as a query param). Retry once or twice if the list is empty. + +--- + +## Session Management + +```python +# Get session details +session = client.beta.sessions.retrieve(session_id="sess_abc123") +print(session.status, session.usage) + +# List sessions +sessions = client.beta.sessions.list() + +# Delete a session +client.beta.sessions.delete(session_id="sess_abc123") + +# Archive a session +client.beta.sessions.archive(session_id="sess_abc123") +``` + +--- + +## MCP Server Integration + +```python +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name="MCP Agent", + model="claude-opus-4-6", + mcp_servers=[ + {"type": "url", "name": "my-tools", "url": "https://my-mcp-server.example.com/sse"}, + ], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "my-tools"}, + ], +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment.id, + vault_ids=[vault.id], +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2285.4/skills/claude-api/ruby/claude-api.md b/junie/versions/2285.4/skills/claude-api/ruby/claude-api.md new file mode 100644 index 0000000..21f5b12 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/ruby/claude-api.md @@ -0,0 +1,113 @@ +# Claude API — Ruby + +> **Note:** The Ruby SDK supports the Claude API. A tool runner is available in beta via `client.beta.messages.tool_runner()`. Agent SDK is not yet available for Ruby. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +--- + +## Basic Message Request + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "What is the capital of France?" } + ] +) +# content is an array of polymorphic block objects (TextBlock, ThinkingBlock, +# ToolUseBlock, ...). .type is a Symbol — compare with :text, not "text". +# .text raises NoMethodError on non-TextBlock entries. +message.content.each do |block| + puts block.text if block.type == :text +end +``` + +--- + +## Streaming + +```ruby +stream = client.messages.stream( + model: :"claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a haiku" }] +) + +stream.text.each { |text| print(text) } +``` + +--- + +## Tool Use + +The Ruby SDK supports tool use via raw JSON schema definitions and also provides a beta tool runner for automatic tool execution. + +### Tool Runner (Beta) + +```ruby +class GetWeatherInput < Anthropic::BaseModel + required :location, String, doc: "City and state, e.g. San Francisco, CA" +end + +class GetWeather < Anthropic::BaseTool + doc "Get the current weather for a location" + + input_schema GetWeatherInput + + def call(input) + "The weather in #{input.location} is sunny and 72°F." + end +end + +client.beta.messages.tool_runner( + model: :"claude-opus-4-6", + max_tokens: 16000, + tools: [GetWeather.new], + messages: [{ role: "user", content: "What's the weather in San Francisco?" }] +).each_message do |message| + puts message.content +end +``` + +### Manual Loop + +See the [shared tool use concepts](../shared/tool-use-concepts.md) for the tool definition format and agentic loop pattern. + +--- + +## Prompt Caching + +`system_:` (trailing underscore — avoids shadowing `Kernel#system`) takes an array of text blocks; set `cache_control` on the last block. Plain hashes work via the `OrHash` type alias. For placement patterns and the silent-invalidator audit checklist, see `shared/prompt-caching.md`. + +```ruby +message = client.messages.create( + model: :"claude-opus-4-6", + max_tokens: 16000, + system_: [ + { type: "text", text: long_system_prompt, cache_control: { type: "ephemeral" } } + ], + messages: [{ role: "user", content: "Summarize the key points" }] +) +``` + +For 1-hour TTL: `cache_control: { type: "ephemeral", ttl: "1h" }`. There's also a top-level `cache_control:` on `messages.create` that auto-places on the last cacheable block. + +Verify hits via `message.usage.cache_creation_input_tokens` / `message.usage.cache_read_input_tokens`. diff --git a/junie/versions/2285.4/skills/claude-api/ruby/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/ruby/managed-agents/README.md new file mode 100644 index 0000000..e6bf24f --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/ruby/managed-agents/README.md @@ -0,0 +1,389 @@ +# Managed Agents — Ruby + +> **Bindings not shown here:** This README covers the most common managed-agents flows for Ruby. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the Ruby SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `client.beta.agents.create` and pass it to every subsequent `client.beta.sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +gem install anthropic +``` + +## Client Initialization + +```ruby +require "anthropic" + +# Default (uses ANTHROPIC_API_KEY env var) +client = Anthropic::Client.new + +# Explicit API key +client = Anthropic::Client.new(api_key: "your-api-key") +``` + +> ⚠️ **Trailing underscores:** The Ruby SDK uses `system_:` and `send_(` (trailing underscore) to avoid shadowing `Kernel#system` and `Kernel#send`. Use these forms throughout managed-agents code. + +--- + +## Create an Environment + +```ruby +environment = client.beta.environments.create( + name: "my-dev-env", + config: { + type: "cloud", + networking: {type: "unrestricted"} + } +) +puts "Environment ID: #{environment.id}" # env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system_`/`tools` live on the agent object, not the session. Always start with `client.beta.agents.create()` — the session takes either `agent: agent.id` or the typed hash form `agent: {type: "agent", id: agent.id, version: agent.version}`. + +### Minimal + +```ruby +# 1. Create the agent (reusable, versioned) +agent = client.beta.agents.create( + name: "Coding Assistant", + model: :"claude-opus-4-6", + system_: "You are a helpful coding assistant.", + tools: [{type: "agent_toolset_20260401"}] +) + +# 2. Start a session +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + title: "Quickstart session" +) +puts "Session ID: #{session.id}" +``` + +### Updating an Agent + +Updates create new versions; the agent object is immutable per version. + +```ruby +updated_agent = client.beta.agents.update( + agent.id, + version: agent.version, + system_: "You are a helpful coding agent. Always write tests." +) +puts "New version: #{updated_agent.version}" + +# List all versions +client.beta.agents.versions.list(agent.id).auto_paging_each do |version| + puts "Version #{version.version}: #{version.updated_at.iso8601}" +end + +# Archive the agent +archived = client.beta.agents.archive(agent.id) +puts "Archived at: #{archived.archived_at.iso8601}" +``` + +--- + +## Send a User Message + +```ruby +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Review the auth module"}] + }] +) +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```ruby +# Open the stream first, then send the user message +stream = client.beta.sessions.events.stream_events(session.id) + +client.beta.sessions.events.send_( + session.id, + events: [{ + type: "user.message", + content: [{type: "text", text: "Summarize the repo README"}] + }] +) + +stream.each do |event| + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"agent.tool_use" + puts "\n[Using tool: #{event.name}]" + in :"session.status_idle" + break + in :"session.error" + puts "\n[Error: #{event.error&.message || "unknown"}]" + break + else + # ignore other event types + end +end +``` + +> ℹ️ Event `.type` is a Symbol (compare with `:"agent.message"`, not `"agent.message"`). + +### Reconnecting and Tailing + +When reconnecting mid-session, list past events first to dedupe, then tail live events: + +```ruby +require "set" + +stream = client.beta.sessions.events.stream_events(session.id) + +# Stream is open and buffering. List history before tailing live. +seen_event_ids = Set.new +client.beta.sessions.events.list(session.id).auto_paging_each { |past| seen_event_ids << past.id } + +# Tail live events, skipping anything already seen +stream.each do |event| + next if seen_event_ids.include?(event.id) + seen_event_ids << event.id + case event.type + in :"agent.message" + event.content.each { |block| print block.text } + in :"session.status_idle" + break + else + # ignore other event types + end +end +``` + +--- + +## Provide Custom Tool Result + +> ℹ️ The Ruby managed-agents bindings for `user.custom_tool_result` are not yet documented in this skill or in the apps source examples. Refer to `shared/managed-agents-events.md` for the wire format and the `anthropic` Ruby gem repository for the corresponding params. + +--- + +## Poll Events + +```ruby +client.beta.sessions.events.list(session.id).auto_paging_each do |event| + puts "#{event.type}: #{event.id}" +end +``` + +--- + +## Upload a File + +```ruby +require "pathname" + +file = client.beta.files.upload(file: Pathname("data.csv")) +puts "File ID: #{file.id}" + +# Mount in a session +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + resources: [ + { + type: "file", + file_id: file.id, + mount_path: "/workspace/data.csv" + } + ] +) +``` + +### Add and Manage Resources on an Existing Session + +```ruby +# Attach an additional file to an open session +resource = client.beta.sessions.resources.add( + session.id, + type: "file", + file_id: file.id +) +puts resource.id # "sesrsc_01ABC..." + +# List resources on the session +listed = client.beta.sessions.resources.list(session.id) +listed.data.each { |entry| puts "#{entry.id} #{entry.type}" } + +# Detach a resource +client.beta.sessions.resources.delete(resource.id, session_id: session.id) +``` + +--- + +## List and Download Session Files + +> ℹ️ Listing and downloading files an agent wrote during a session is not yet documented for Ruby in this skill or in the apps source examples. See `shared/managed-agents-events.md` and the `anthropic` Ruby gem repository for the file list/download bindings. + +--- + +## Session Management + +```ruby +# List environments +environments = client.beta.environments.list + +# Retrieve a specific environment +env = client.beta.environments.retrieve(environment.id) + +# Archive an environment (read-only, existing sessions continue) +client.beta.environments.archive(environment.id) + +# Delete an environment (only if no sessions reference it) +client.beta.environments.delete(environment.id) + +# Delete a session +client.beta.sessions.delete(session.id) +``` + +--- + +## MCP Server Integration + +```ruby +# Agent declares MCP server (no auth here — auth goes in a vault) +agent = client.beta.agents.create( + name: "GitHub Assistant", + model: :"claude-opus-4-6", + mcp_servers: [ + { + type: "url", + name: "github", + url: "https://api.githubcopilot.com/mcp/" + } + ], + tools: [ + {type: "agent_toolset_20260401"}, + {type: "mcp_toolset", mcp_server_name: "github"} + ] +) + +# Session attaches vault(s) containing credentials for those MCP server URLs +session = client.beta.sessions.create( + agent: {type: "agent", id: agent.id, version: agent.version}, + environment_id: environment.id, + vault_ids: [vault.id] +) +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. + +--- + +## Vaults + +```ruby +# Create a vault +vault = client.beta.vaults.create( + display_name: "Alice", + metadata: {external_user_id: "usr_abc123"} +) +puts vault.id # "vlt_01ABC..." + +# Add an OAuth credential +credential = client.beta.vaults.credentials.create( + vault.id, + display_name: "Alice's Slack", + auth: { + type: "mcp_oauth", + mcp_server_url: "https://mcp.slack.com/mcp", + access_token: "xoxp-...", + expires_at: "2026-04-15T00:00:00Z", + refresh: { + token_endpoint: "https://slack.com/api/oauth.v2.access", + client_id: "1234567890.0987654321", + scope: "channels:read chat:write", + refresh_token: "xoxe-1-...", + token_endpoint_auth: { + type: "client_secret_post", + client_secret: "abc123..." + } + } + } +) + +# Rotate the credential (e.g., after a token refresh) +client.beta.vaults.credentials.update( + credential.id, + vault_id: vault.id, + auth: { + type: "mcp_oauth", + access_token: "xoxp-new-...", + expires_at: "2026-05-15T00:00:00Z", + refresh: {refresh_token: "xoxe-1-new-..."} + } +) + +# Archive a vault +client.beta.vaults.archive(vault.id) +``` + +--- + +## GitHub Repository Integration + +Mount a GitHub repository as a session resource (a vault holds the GitHub MCP credential): + +```ruby +session = client.beta.sessions.create( + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], + resources: [ + { + type: "github_repository", + url: "https://github.com/org/repo", + mount_path: "/workspace/repo", + authorization_token: "ghp_your_github_token" + } + ] +) +``` + +Multiple repositories on the same session: + +```ruby +resources = [ + { + type: "github_repository", + url: "https://github.com/org/frontend", + mount_path: "/workspace/frontend", + authorization_token: "ghp_your_github_token" + }, + { + type: "github_repository", + url: "https://github.com/org/backend", + mount_path: "/workspace/backend", + authorization_token: "ghp_your_github_token" + } +] +``` + +Rotating a repository's authorization token: + +```ruby +listed = client.beta.sessions.resources.list(session.id) +repo_resource_id = listed.data.first.id + +client.beta.sessions.resources.update( + repo_resource_id, + session_id: session.id, + authorization_token: "ghp_your_new_github_token" +) +``` diff --git a/junie/versions/2285.4/skills/claude-api/shared/agent-design.md b/junie/versions/2285.4/skills/claude-api/shared/agent-design.md new file mode 100644 index 0000000..6756c39 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/agent-design.md @@ -0,0 +1,101 @@ +# Agent Design Patterns + +This file covers decision heuristics for building agents on the Claude API: which primitives to reach for, how to design your tool surface, and how to manage context and cost over long runs. For per-tool mechanics and code examples, see `tool-use-concepts.md` and the language-specific folders. + +--- + +## Model Parameters + +| Parameter | When to use it | What to expect | +| --- | --- | --- | +| **Adaptive thinking** (`thinking: {type: "adaptive"}`) | When you want Claude to control when and how much to think. | Claude determines thinking depth per request and automatically interleaves thinking between tool calls. No token budget to tune. | +| **Effort** (`output_config: {effort: ...}`) | When adjusting the tradeoff between thoroughness and token efficiency. | Lower effort → fewer and more-consolidated tool calls, less preamble, terser confirmations. `medium` is often a favorable balance. Use `max` when correctness matters more than cost. | + +See `SKILL.md` §Thinking & Effort for model support and parameter details. + +--- + +## Designing Your Tool Surface + +### Bash vs. dedicated tools + +Claude doesn't know your application's security boundary, approval policy, or UX surface. Claude emits tool calls; your harness handles them. The shape of those tool calls determines what the harness can do. + +A **bash tool** gives Claude broad programmatic leverage — it can perform almost any action. But it gives the harness only an opaque command string, the same shape for every action. Promoting an action to a **dedicated tool** gives the harness an action-specific hook with typed arguments it can intercept, gate, render, or audit. + +**When to promote an action to a dedicated tool:** + +- **Security boundary.** Actions that require gating are natural candidates. Reversibility is a useful criterion: hard-to-reverse actions (external API calls, sending messages, deleting data) can be gated behind user confirmation. A `send_email` tool is easy to gate; `bash -c "curl -X POST ..."` is not. +- **Staleness checks.** A dedicated `edit` tool can reject writes if the file changed since Claude last read it. Bash can't enforce that invariant. +- **Rendering.** Some actions benefit from custom UI. Claude Code promotes question-asking to a tool so it can render as a modal, present options, and block the agent loop until answered. +- **Scheduling.** Read-only tools like `glob` and `grep` can be marked parallel-safe. When the same actions run through bash, the harness can't tell a parallel-safe `grep` from a parallel-unsafe `git push`, so it must serialize. + +**Rule of thumb:** Start with bash for breadth. Promote to dedicated tools when you need to gate, render, audit, or parallelize the action. + +--- + +## Anthropic-Provided Tools + +| Tool | Side | When to use it | What to expect | +| --- | --- | --- | --- | +| **Bash** | Client | Claude needs to execute shell commands. | Claude emits commands; your harness executes them. Reference implementation provided. | +| **Text editor** | Client | Claude needs to read or edit files. | Claude views, creates, and edits files via your implementation. Reference implementation provided. | +| **Computer use** | Client or Server | Claude needs to interact with GUIs, web apps, or visual interfaces. | Claude takes screenshots and issues mouse/keyboard commands. Can be self-hosted (you run the environment) or Anthropic-hosted. | +| **Code execution** | Server | Claude needs to run code in a sandbox you don't want to manage. | Anthropic-hosted container with built-in file and bash sub-tools. No client-side execution. | +| **Web search / fetch** | Server | Claude needs information past its training cutoff (news, current events, recent docs) or the content of a specific URL. | Claude issues a query or URL; Anthropic executes it and returns results with citations. | +| **Memory** | Client | Claude needs to save context across sessions. | Claude reads/writes a `/memories` directory. You implement the storage backend. | + +**Client-side** tools are defined by Anthropic (name, schema, Claude's usage pattern) but executed by your harness. Anthropic provides reference implementations. **Server-side** tools run entirely on Anthropic infrastructure — declare them in `tools` and Claude handles the rest. + +--- + +## Composing Tool Calls: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls the tool, the result lands in Claude's context, Claude reasons about it, then calls the next tool. Three sequential actions (read profile → look up orders → check inventory) means three round trips. Each adds latency and tokens, and most of the intermediate data is never needed again. + +**Programmatic tool calling (PTC)** lets Claude compose those calls into a script instead. The script runs in the code execution container. When the script calls a tool, the container pauses, the call is executed (client-side or server-side), and the result returns to the running code — not to Claude's context. The script processes it with normal control flow (loops, filters, branches). Only the script's final output returns to Claude. + +| When to use it | What to expect | +| --- | --- | +| Many sequential tool calls, or large intermediate results you want filtered before they hit the context window. | Claude writes code that invokes tools as functions. Runs in the code execution container. Token cost scales with final output, not intermediate results. | + +--- + +## Scaling the Tool and Instruction Set + +| Feature | When to use it | What to expect | +| --- | --- | --- | +| **Tool search** | Many tools available, but only a few relevant per request. Don't want all schemas in context upfront. | Claude searches the tool set and loads only relevant schemas. Tool definitions are appended, not swapped — preserves cache (see Caching below). | +| **Skills** | Task-specific instructions Claude should load only when relevant. | Each skill is a folder with a `SKILL.md`. The skill's description sits in context by default; Claude reads the full file when the task calls for it. | + +Both patterns keep the fixed context small and load detail on demand. + +--- + +## Long-Running Agents: Managing Context + +| Pattern | When to use it | What to expect | +| --- | --- | --- | +| **Context editing** | Context grows stale over many turns (old tool results, completed thinking). | Tool results and thinking blocks are cleared based on configurable thresholds. Keeps the transcript lean without summarizing. | +| **Compaction** | Conversation likely to reach or exceed the context window limit. | Earlier context is summarized into a compaction block server-side. See `SKILL.md` §Compaction for the critical `response.content` handling. | +| **Memory** | State must persist across sessions (not just within one conversation). | Claude reads/writes files in a memory directory. Survives process restarts. | + +**Choosing between them:** Context editing and compaction operate within a session — editing prunes stale turns, compaction summarizes when you're near the limit. Memory is for cross-session persistence. Many long-running agents use all three. + +--- + +## Caching for Agents + +**Read `prompt-caching.md` first.** It covers the prefix-match invariant, breakpoint placement, the silent-invalidator audit, and why changing tools or models mid-session breaks the cache. This section covers only the agent-specific workarounds for those constraints. + +| Constraint (from `prompt-caching.md`) | Agent-specific workaround | +| --- | --- | +| Editing the system prompt mid-session invalidates the cache. | Append a `` block in the `messages` array instead. The cached prefix stays intact. Claude Code uses this for time updates and mode transitions. | +| Switching models mid-session invalidates the cache. | Spawn a **subagent** with the cheaper model for the sub-task; keep the main loop on one model. Claude Code's Explore subagents use Haiku this way. | +| Adding/removing tools mid-session invalidates the cache. | Use **tool search** for dynamic discovery — it appends tool schemas rather than swapping them, so the existing prefix is preserved. | + +For multi-turn breakpoint placement, use top-level auto-caching — see `prompt-caching.md` §Placement patterns. + +--- + +For live documentation on any of these features, see `live-sources.md`. diff --git a/junie/versions/2285.4/skills/claude-api/shared/error-codes.md b/junie/versions/2285.4/skills/claude-api/shared/error-codes.md new file mode 100644 index 0000000..9d08498 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/error-codes.md @@ -0,0 +1,206 @@ +# HTTP Error Codes Reference + +This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders. + +## Error Code Summary + +| Code | Error Type | Retryable | Common Cause | +| ---- | ----------------------- | --------- | ------------------------------------ | +| 400 | `invalid_request_error` | No | Invalid request format or parameters | +| 401 | `authentication_error` | No | Invalid or missing API key | +| 403 | `permission_error` | No | API key lacks permission | +| 404 | `not_found_error` | No | Invalid endpoint or model ID | +| 413 | `request_too_large` | No | Request exceeds size limits | +| 429 | `rate_limit_error` | Yes | Too many requests | +| 500 | `api_error` | Yes | Anthropic service issue | +| 529 | `overloaded_error` | Yes | API is temporarily overloaded | + +## Detailed Error Information + +### 400 Bad Request + +**Causes:** + +- Malformed JSON in request body +- Missing required parameters (`model`, `max_tokens`, `messages`) +- Invalid parameter types (e.g., string where integer expected) +- Empty messages array +- Messages not alternating user/assistant + +**Example error:** + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "messages: roles must alternate between \"user\" and \"assistant\"" + }, + "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy" +} +``` + +**Fix:** Validate request structure before sending. Check that: + +- `model` is a valid model ID +- `max_tokens` is a positive integer +- `messages` array is non-empty and alternates correctly + +--- + +### 401 Unauthorized + +**Causes:** + +- Missing `x-api-key` header or `Authorization` header +- Invalid API key format +- Revoked or deleted API key + +**Fix:** Ensure `ANTHROPIC_API_KEY` environment variable is set correctly. + +--- + +### 403 Forbidden + +**Causes:** + +- API key doesn't have access to the requested model +- Organization-level restrictions +- Attempting to access beta features without beta access + +**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features. + +--- + +### 404 Not Found + +**Causes:** + +- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`) +- Using deprecated model ID +- Invalid API endpoint + +**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-4-6`). + +--- + +### 413 Request Too Large + +**Causes:** + +- Request body exceeds maximum size +- Too many tokens in input +- Image data too large + +**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks. + +--- + +### 400 Validation Errors + +Some 400 errors are specifically related to parameter validation: + +- `max_tokens` exceeds model's limit +- Invalid `temperature` value (must be 0.0-1.0) +- `budget_tokens` >= `max_tokens` in extended thinking +- Invalid tool definition schema + +**Common mistake with extended thinking:** + +``` +# Wrong: budget_tokens must be < max_tokens +thinking: budget_tokens=10000, max_tokens=1000 → Error! + +# Correct +thinking: budget_tokens=10000, max_tokens=16000 +``` + +--- + +### 429 Rate Limited + +**Causes:** + +- Exceeded requests per minute (RPM) +- Exceeded tokens per minute (TPM) +- Exceeded tokens per day (TPD) + +**Headers to check:** + +- `retry-after`: Seconds to wait before retrying +- `x-ratelimit-limit-*`: Your limits +- `x-ratelimit-remaining-*`: Remaining quota + +**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples. + +--- + +### 500 Internal Server Error + +**Causes:** + +- Temporary Anthropic service issue +- Bug in API processing + +**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com). + +--- + +### 529 Overloaded + +**Causes:** + +- High API demand +- Service capacity reached + +**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing. + +--- + +## Common Mistakes and Fixes + +| Mistake | Error | Fix | +| ------------------------------- | ---------------- | ------------------------------------------------------- | +| `budget_tokens` >= `max_tokens` | 400 | Ensure `budget_tokens` < `max_tokens` | +| Typo in model ID | 404 | Use valid model ID like `claude-opus-4-6` | +| First message is `assistant` | 400 | First message must be `user` | +| Consecutive same-role messages | 400 | Alternate `user` and `assistant` | +| API key in code | 401 (leaked key) | Use environment variable | +| Custom retry needs | 429/5xx | SDK retries automatically; customize with `max_retries` | + +## Typed Exceptions in SDKs + +**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP error code maps to a specific exception class: + +| HTTP Code | TypeScript Class | Python Class | +| --------- | --------------------------------- | --------------------------------- | +| 400 | `Anthropic.BadRequestError` | `anthropic.BadRequestError` | +| 401 | `Anthropic.AuthenticationError` | `anthropic.AuthenticationError` | +| 403 | `Anthropic.PermissionDeniedError` | `anthropic.PermissionDeniedError` | +| 404 | `Anthropic.NotFoundError` | `anthropic.NotFoundError` | +| 429 | `Anthropic.RateLimitError` | `anthropic.RateLimitError` | +| 500+ | `Anthropic.InternalServerError` | `anthropic.InternalServerError` | +| Any | `Anthropic.APIError` | `anthropic.APIError` | + +```typescript +// ✅ Correct: use typed exceptions +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.RateLimitError) { + // Handle rate limiting + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} + +// ❌ Wrong: don't check error messages with string matching +try { + const response = await client.messages.create({...}); +} catch (error) { + const msg = error instanceof Error ? error.message : String(error); + if (msg.includes("429") || msg.includes("rate_limit")) { ... } +} +``` + +All exception classes extend `Anthropic.APIError`, which has a `status` property. Use `instanceof` checks from most specific to least specific (e.g., check `RateLimitError` before `APIError`). diff --git a/junie/versions/2285.4/skills/claude-api/shared/live-sources.md b/junie/versions/2285.4/skills/claude-api/shared/live-sources.md new file mode 100644 index 0000000..343e9d7 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/live-sources.md @@ -0,0 +1,131 @@ +# Live Documentation Sources + +This file contains WebFetch URLs for fetching current information from platform.claude.com and Agent SDK repositories. Use these when users need the latest data that may have changed since the cached content was last updated. + +## When to Use WebFetch + +- User explicitly asks for "latest" or "current" information +- Cached data seems incorrect +- User asks about features not covered in cached content +- User needs specific API details or examples + +## Claude API Documentation URLs + +### Models & Pricing + +| Topic | URL | Extraction Prompt | +| --------------- | --------------------------------------------------------------------- | ------------------------------------------------------------------------------- | +| Models Overview | `https://platform.claude.com/docs/en/about-claude/models/overview.md` | "Extract current model IDs, context windows, and pricing for all Claude models" | +| Pricing | `https://platform.claude.com/docs/en/pricing.md` | "Extract current pricing per million tokens for input and output" | + +### Core Features + +| Topic | URL | Extraction Prompt | +| ----------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| Extended Thinking | `https://platform.claude.com/docs/en/build-with-claude/extended-thinking.md` | "Extract extended thinking parameters, budget_tokens requirements, and usage examples" | +| Adaptive Thinking | `https://platform.claude.com/docs/en/build-with-claude/adaptive-thinking.md` | "Extract adaptive thinking setup, effort levels, and Claude Opus 4.6 usage examples" | +| Effort Parameter | `https://platform.claude.com/docs/en/build-with-claude/effort.md` | "Extract effort levels, cost-quality tradeoffs, and interaction with thinking" | +| Tool Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview.md` | "Extract tool definition schema, tool_choice options, and handling tool results" | +| Streaming | `https://platform.claude.com/docs/en/build-with-claude/streaming.md` | "Extract streaming event types, SDK examples, and best practices" | +| Prompt Caching | `https://platform.claude.com/docs/en/build-with-claude/prompt-caching.md` | "Extract cache_control usage, pricing benefits, and implementation examples" | + +### Media & Files + +| Topic | URL | Extraction Prompt | +| ----------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------- | +| Vision | `https://platform.claude.com/docs/en/build-with-claude/vision.md` | "Extract supported image formats, size limits, and code examples" | +| PDF Support | `https://platform.claude.com/docs/en/build-with-claude/pdf-support.md` | "Extract PDF handling capabilities, limits, and examples" | + +### API Operations + +| Topic | URL | Extraction Prompt | +| ---------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | +| Batch Processing | `https://platform.claude.com/docs/en/build-with-claude/batch-processing.md` | "Extract batch API endpoints, request format, and polling for results" | +| Files API | `https://platform.claude.com/docs/en/build-with-claude/files.md` | "Extract file upload, download, and referencing in messages, including supported types and beta header" | +| Token Counting | `https://platform.claude.com/docs/en/build-with-claude/token-counting.md` | "Extract token counting API usage and examples" | +| Rate Limits | `https://platform.claude.com/docs/en/api/rate-limits.md` | "Extract current rate limits by tier and model" | +| Errors | `https://platform.claude.com/docs/en/api/errors.md` | "Extract HTTP error codes, meanings, and retry guidance" | + +### Tools + +| Topic | URL | Extraction Prompt | +| -------------- | -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- | +| Code Execution | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/code-execution-tool.md` | "Extract code execution tool setup, file upload, container reuse, and response handling" | +| Computer Use | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use.md` | "Extract computer use tool setup, capabilities, and implementation examples" | +| Bash Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/bash-tool.md` | "Extract bash tool schema, reference implementation, and security considerations" | +| Text Editor | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/text-editor-tool.md` | "Extract text editor tool commands, schema, and reference implementation" | +| Memory Tool | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` | "Extract memory tool commands, directory structure, and implementation patterns" | +| Tool Search | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool.md` | "Extract tool search setup, when to use, and cache interaction" | +| Programmatic Tool Calling | `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling.md` | "Extract PTC setup, script execution model, and tool invocation from code" | +| Skills | `https://platform.claude.com/docs/en/agents-and-tools/skills.md` | "Extract skill folder structure, SKILL.md format, and loading behavior" | + +### Advanced Features + +| Topic | URL | Extraction Prompt | +| ------------------ | ----------------------------------------------------------------------------- | --------------------------------------------------- | +| Structured Outputs | `https://platform.claude.com/docs/en/build-with-claude/structured-outputs.md` | "Extract output_config.format usage and schema enforcement" | +| Compaction | `https://platform.claude.com/docs/en/build-with-claude/compaction.md` | "Extract compaction setup, trigger config, and streaming with compaction" | +| Context Editing | `https://platform.claude.com/docs/en/build-with-claude/context-editing.md` | "Extract context editing thresholds, what gets cleared, and configuration" | +| Citations | `https://platform.claude.com/docs/en/build-with-claude/citations.md` | "Extract citation format and implementation" | +| Context Windows | `https://platform.claude.com/docs/en/build-with-claude/context-windows.md` | "Extract context window sizes and token management" | + +### Managed Agents + +Use these when a managed-agents binding, behavior, or wire-level detail isn't covered in the cached `shared/managed-agents-*.md` concept files or in `{lang}/managed-agents/README.md`. + +| Topic | URL | Extraction Prompt | +| --------------------- | -------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | +| Overview | `https://platform.claude.com/docs/en/managed-agents/overview.md` | "Extract the high-level architecture and how agents/sessions/environments/vaults fit together" | +| Quickstart | `https://platform.claude.com/docs/en/managed-agents/quickstart.md` | "Extract the minimal end-to-end agent → environment → session → stream code path" | +| Agent Setup | `https://platform.claude.com/docs/en/managed-agents/agent-setup.md` | "Extract agent create/update/list-versions/archive lifecycle and parameters" | +| Define Outcomes | `https://platform.claude.com/docs/en/managed-agents/define-outcomes.md` | "Extract outcome definitions, evaluation hooks, and success criteria configuration" | +| Sessions | `https://platform.claude.com/docs/en/managed-agents/sessions.md` | "Extract session lifecycle, status transitions, idle/terminated semantics, and resume rules" | +| Environments | `https://platform.claude.com/docs/en/managed-agents/environments.md` | "Extract environment config (cloud/networking), management endpoints, and reuse model" | +| Events and Streaming | `https://platform.claude.com/docs/en/managed-agents/events-and-streaming.md` | "Extract event stream types, stream-first ordering, reconnect/dedupe, and steering patterns" | +| Tools | `https://platform.claude.com/docs/en/managed-agents/tools.md` | "Extract built-in toolset, custom tool definitions, and tool result wire format" | +| Files | `https://platform.claude.com/docs/en/managed-agents/files.md` | "Extract file upload, mount paths, session resources, and listing/downloading session outputs" | +| Permission Policies | `https://platform.claude.com/docs/en/managed-agents/permission-policies.md` | "Extract permission policy types (allow/deny/confirm) and per-tool config" | +| Multi-Agent | `https://platform.claude.com/docs/en/managed-agents/multi-agent.md` | "Extract multi-agent composition patterns, sub-agent invocation, and result handoff" | +| Observability | `https://platform.claude.com/docs/en/managed-agents/observability.md` | "Extract logging, tracing, and usage telemetry exposed by managed agents" | +| GitHub | `https://platform.claude.com/docs/en/managed-agents/github.md` | "Extract github_repository resource shape, multi-repo mounting, and token rotation" | +| MCP Connector | `https://platform.claude.com/docs/en/managed-agents/mcp-connector.md` | "Extract MCP server declaration on agents and vault-based credential injection at session" | +| Vaults | `https://platform.claude.com/docs/en/managed-agents/vaults.md` | "Extract vault create, credential add/rotate, OAuth refresh shape, and archive" | +| Skills | `https://platform.claude.com/docs/en/managed-agents/skills.md` | "Extract skill packaging and loading model for managed agents" | +| Memory | `https://platform.claude.com/docs/en/managed-agents/memory.md` | "Extract memory resource shape, scoping, and lifecycle" | +| Onboarding | `https://platform.claude.com/docs/en/managed-agents/onboarding.md` | "Extract first-run setup, prerequisites, and account/region requirements" | +| Cloud Containers | `https://platform.claude.com/docs/en/managed-agents/cloud-containers.md` | "Extract cloud container runtime, image config, and network/storage knobs" | +| Migration | `https://platform.claude.com/docs/en/managed-agents/migration.md` | "Extract migration paths from earlier APIs/preview shapes to GA managed agents" | + +### Anthropic CLI + +The `ant` CLI provides terminal access to the Claude API. Every API resource is exposed as a subcommand. It is one convenient way to create agents, environments, sessions, and other resources from version-controlled YAML, and to inspect responses interactively. + +| Topic | URL | Extraction Prompt | +| ------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | +| Anthropic CLI | `https://platform.claude.com/docs/en/api/sdks/cli.md` | "Extract CLI install, authentication, command structure, and the beta:agents/environments/sessions commands" | + +--- + +## Claude API SDK Repositories + +WebFetch these when a binding (class, method, namespace, field) isn't covered in the cached `{lang}/` skill files or in the managed-agents docs above. The SDKs include beta managed-agents support for `/v1/agents`, `/v1/sessions`, `/v1/environments`, and related resources — search the repo for `BetaManagedAgents`, `beta.agents`, `beta.sessions`, or the equivalent namespace for that language. + +| SDK | URL | Extraction Prompt | +| ---------- | -------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- | +| Python | `https://github.com/anthropics/anthropic-sdk-python` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| TypeScript | `https://github.com/anthropics/anthropic-sdk-typescript` | "Extract beta managed-agents namespaces, classes, and method signatures (`client.beta.agents`, `client.beta.sessions`)" | +| Java | `https://github.com/anthropics/anthropic-sdk-java` | "Extract beta managed-agents classes, builders, and method signatures (`client.beta().agents()`, `BetaManagedAgents*`)" | +| Go | `https://github.com/anthropics/anthropic-sdk-go` | "Extract beta managed-agents types and method signatures (`client.Beta.Agents`, `BetaManagedAgents*` event types)" | +| Ruby | `https://github.com/anthropics/anthropic-sdk-ruby` | "Extract beta managed-agents methods and parameter shapes (`client.beta.agents`, `client.beta.sessions`)" | +| C# | `https://github.com/anthropics/anthropic-sdk-csharp` | "Extract beta managed-agents classes and method signatures (NuGet package, `BetaManagedAgents*` types)" | +| PHP | `https://github.com/anthropics/anthropic-sdk-php` | "Extract beta managed-agents classes and method signatures (`$client->beta->agents`, `BetaManagedAgents*` params)" | + +--- + +## Fallback Strategy + +If WebFetch fails (network issues, URL changed): + +1. Use cached content from the language-specific files (note the cache date) +2. Inform user the data may be outdated +3. Suggest they check platform.claude.com or the GitHub repos directly diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-api-reference.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-api-reference.md new file mode 100644 index 0000000..155c877 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-api-reference.md @@ -0,0 +1,299 @@ +# Managed Agents — Endpoint Reference + +All endpoints require `x-api-key` and `anthropic-version: 2023-06-01` headers. Managed Agents endpoints additionally require the `anthropic-beta` header. + +## Beta Headers + +``` +anthropic-beta: managed-agents-2026-04-01 +``` + +The SDK adds this header automatically for all `client.beta.{agents,environments,sessions,vaults}.*` calls. Skills endpoints use `skills-2025-10-02`; Files endpoints use `files-api-2025-04-14`. + +--- + +## SDK Method Reference + +All resources are under the `beta` namespace. Python and TypeScript share identical method names. + +| Resource | Python / TypeScript (`client.beta.*`) | Go (`client.Beta.*`) | +| --- | --- | --- | +| Agents | `agents.create` / `retrieve` / `update` / `list` / `archive` | `Agents.New` / `Get` / `Update` / `List` / `Archive` | +| Agent Versions | `agents.versions.list` | `Agents.Versions.List` | +| Environments | `environments.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Environments.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Sessions | `sessions.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Sessions.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Session Events | `sessions.events.list` / `send` / `stream` | `Sessions.Events.List` / `Send` / `StreamEvents` | +| Session Resources | `sessions.resources.add` / `retrieve` / `update` / `list` / `delete` | `Sessions.Resources.Add` / `Get` / `Update` / `List` / `Delete` | +| Vaults | `vaults.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | +| Credentials | `vaults.credentials.create` / `retrieve` / `update` / `list` / `delete` / `archive` | `Vaults.Credentials.New` / `Get` / `Update` / `List` / `Delete` / `Archive` | + +**Naming quirks to watch for:** +- Agents have **no delete** — only `archive`. Other resources have both. +- Session resources use `add` (not `create`). +- Go's event stream is `StreamEvents` (not `Stream`). + +**Agent shorthand:** `agent` on session create accepts either a bare string (`agent="agent_abc123"` — uses latest version) or the full reference object (`{type: "agent", id: "agent_abc123", version: 123}`). + +**Model shorthand:** `model` on agent create accepts either a bare string (`model="claude-opus-4-6"` — uses `standard` speed) or the full config object (`{type: "model_config", id: "claude-opus-4-6", speed: "fast"}`). + +--- + +## Agents + +**Step one of every flow.** Sessions require a pre-created agent — there is no inline agent config under `managed-agents-2026-04-01`. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/agents` | ListAgents | List agents | +| `POST` | `/v1/agents` | CreateAgent | Create a saved agent configuration | +| `GET` | `/v1/agents/{agent_id}` | GetAgent | Get agent details | +| `POST` | `/v1/agents/{agent_id}` | UpdateAgent | Update agent configuration | +| `POST` | `/v1/agents/{agent_id}/archive` | ArchiveAgent | Archive an agent (no hard delete for agents) | +| `GET` | `/v1/agents/{agent_id}/versions` | ListAgentVersions | List agent versions | + +## Sessions + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions` | ListSessions | List sessions (paginated) | +| `POST` | `/v1/sessions` | CreateSession | Create a new session | +| `GET` | `/v1/sessions/{session_id}` | GetSession | Get session details | +| `POST` | `/v1/sessions/{session_id}` | UpdateSession | Update session metadata/title | +| `DELETE` | `/v1/sessions/{session_id}` | DeleteSession | Delete a session | +| `POST` | `/v1/sessions/{session_id}/archive` | ArchiveSession | Archive a session | + +## Events + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/events` | ListEvents | List events (polling, paginated) | +| `POST` | `/v1/sessions/{session_id}/events` | SendEvents | Send events (user message, tool result) | +| `GET` | `/v1/sessions/{session_id}/events/stream` | StreamEvents | Stream events via SSE | + +## Session Resources + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------------- | ---------------- | ---------------------------------------- | +| `GET` | `/v1/sessions/{session_id}/resources` | ListResources | List resources attached to session | +| `POST` | `/v1/sessions/{session_id}/resources` | AddResource | Attach file or github_repository mount (SDK method: `add`, not `create`) | +| `GET` | `/v1/sessions/{session_id}/resources/{resource_id}` | GetResource | Get a single resource | +| `POST` | `/v1/sessions/{session_id}/resources/{resource_id}` | UpdateResource | Update resource | +| `DELETE` | `/v1/sessions/{session_id}/resources/{resource_id}` | DeleteResource | Remove resource from session | + +## Environments + +| Method | Path | Operation | Description | +| -------- | ---------------------------------------------------------------- | -------------------- | ----------------------------------- | +| `POST` | `/v1/environments` | CreateEnvironment | Create environment | +| `GET` | `/v1/environments` | ListEnvironments | List environments | +| `GET` | `/v1/environments/{environment_id}` | GetEnvironment | Get environment details | +| `POST` | `/v1/environments/{environment_id}` | UpdateEnvironment | Update environment | +| `DELETE` | `/v1/environments/{environment_id}` | DeleteEnvironment | Delete environment. Returns 204. | +| `POST` | `/v1/environments/{environment_id}/archive` | ArchiveEnvironment | Archive environment (read-only; existing sessions continue) | + +## Vaults + +Vaults store MCP credentials that Anthropic manages on your behalf — OAuth credentials with auto-refresh, or static bearer tokens. Attach to sessions via `vault_ids`. See `managed-agents-tools.md` §Vaults for the conceptual guide and credential shapes. + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/vaults` | CreateVault | Create a vault | +| `GET` | `/v1/vaults` | ListVaults | List vaults | +| `GET` | `/v1/vaults/{vault_id}` | GetVault | Get vault details | +| `POST` | `/v1/vaults/{vault_id}` | UpdateVault | Update vault | +| `DELETE` | `/v1/vaults/{vault_id}` | DeleteVault | Delete vault | +| `POST` | `/v1/vaults/{vault_id}/archive` | ArchiveVault | Archive vault | + +## Credentials + +Credentials are individual secrets stored inside a vault. + +| Method | Path | Operation | Description | +| -------- | ----------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/vaults/{vault_id}/credentials` | CreateCredential | Create a credential | +| `GET` | `/v1/vaults/{vault_id}/credentials` | ListCredentials | List credentials in vault | +| `GET` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | GetCredential | Get credential metadata | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | UpdateCredential | Update credential | +| `DELETE` | `/v1/vaults/{vault_id}/credentials/{credential_id}` | DeleteCredential | Delete credential | +| `POST` | `/v1/vaults/{vault_id}/credentials/{credential_id}/archive` | ArchiveCredential | Archive credential | + +## Files + +| Method | Path | Operation | Description | +| -------- | ------------------------------------------------ | ---------------- | ---------------------------------------- | +| `POST` | `/v1/files` | UploadFile | Upload a file | +| `GET` | `/v1/files` | ListFiles | List files | +| `GET` | `/v1/files/{file_id}` | GetFile | Get file metadata (SDK method: `retrieve_metadata`) | +| `GET` | `/v1/files/{file_id}/content` | DownloadFile | Download file content | +| `DELETE` | `/v1/files/{file_id}` | DeleteFile | Delete a file | + +## Skills + +| Method | Path | Operation | Description | +| -------- | --------------------------------------------------------------- | ------------------ | ---------------------------- | +| `POST` | `/v1/skills` | CreateSkill | Create a skill | +| `GET` | `/v1/skills` | ListSkills | List skills | +| `GET` | `/v1/skills/{skill_id}` | GetSkill | Get skill details | +| `DELETE` | `/v1/skills/{skill_id}` | DeleteSkill | Delete a skill | +| `POST` | `/v1/skills/{skill_id}/versions` | CreateVersion | Create skill version | +| `GET` | `/v1/skills/{skill_id}/versions` | ListVersions | List skill versions | +| `GET` | `/v1/skills/{skill_id}/versions/{version}` | GetVersion | Get skill version | +| `DELETE` | `/v1/skills/{skill_id}/versions/{version}` | DeleteVersion | Delete skill version | + +--- + +## Request/Response Schema Quick Reference + +### CreateAgent Request Body + +**Always start here.** `model`, `system`, `tools`, `mcp_servers`, `skills` are top-level fields on this object — they do NOT go on the session. + +```json +{ + "name": "string (required, 1-256 chars)", + "model": "claude-opus-4-6 (required — bare string, or {id, speed} object)", + "description": "string (optional, up to 2048 chars)", + "system": "string (optional, up to 100,000 chars)", + "tools": [ + { "type": "agent_toolset_20260401" } + ], + "skills": [ + { "type": "anthropic", "skill_id": "xlsx" }, + { "type": "custom", "skill_id": "skill_abc123", "version": "1" } + ], + "mcp_servers": [ + { + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/" + } + ], + "metadata": { + "key": "value (max 16 pairs, keys ≤64 chars, values ≤512 chars)" + } +} +``` + +> Limits: `tools` max 50, `skills` max 64, `mcp_servers` max 20 (unique names). + +### CreateSession Request Body + +```json +{ + "agent": "agent_abc123 (required — string shorthand for latest version, or {type: \"agent\", id, version} object)", + "environment_id": "env_abc123 (required)", + "title": "string (optional)", + "resources": [ + { + "type": "github_repository", + "url": "https://github.com/owner/repo (required)", + "authorization_token": "ghp_... (required)", + "mount_path": "/workspace/repo (optional — defaults to /workspace/)", + "checkout": { "type": "branch", "name": "main" } + } + ], + "vault_ids": ["vlt_abc123 (optional — MCP credentials with auto-refresh)"], + "metadata": { + "key": "value" + } +} +``` + +> The `agent` field accepts only a string ID or `{type: "agent", id, version}` — `model`/`system`/`tools` live on the agent, not here. +> +> **`checkout`** accepts `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Omit for the repo's default branch. + +### CreateEnvironment Request Body + +```json +{ + "name": "string (required)", + "description": "string (optional)", + "config": { + "type": "cloud", + "networking": { + "type": "unrestricted | limited (union — see SDK types)" + }, + "packages": { } + }, + "metadata": { "key": "value" } +} +``` + +### SendEvents Request Body + +```json +{ + "events": [ + { + "type": "user.message", + "content": [ + { + "type": "text", + "text": "Hello" + } + ] + } + ] +} +``` + +### Tool Result Event + +```json +{ + "type": "user.custom_tool_result", + "custom_tool_use_id": "sevt_abc123", + "content": [{ "type": "text", "text": "Result data" }], + "is_error": false +} +``` + +--- + +## Error Handling + +Managed Agents endpoints use the standard Anthropic API error format. Errors are returned with an HTTP status code and a JSON body containing `type`, `error`, and `request_id`: + +```json +{ + "type": "error", + "error": { + "type": "invalid_request_error", + "message": "Description of what went wrong" + }, + "request_id": "req_011CRv1W3XQ8XpFikNYG7RnE" +} +``` + +Include the `request_id` when reporting issues to Anthropic — it lets us trace the request end-to-end. The inner `error.type` is one of the following: + +| Status | Error type | Description | +|---|---|---| +| 400 | `invalid_request_error` | The request was malformed or missing required parameters | +| 401 | `authentication_error` | Invalid or missing API key | +| 403 | `permission_error` | The API key doesn't have permission for this operation | +| 404 | `not_found_error` | The requested resource doesn't exist | +| 409 | `invalid_request_error` | The request conflicts with the resource's current state (e.g., sending to an archived session) | +| 413 | `request_too_large` | The request body exceeds the maximum allowed size | +| 429 | `rate_limit_error` | Too many requests — check rate limit headers for retry timing | +| 500 | `api_error` | An internal server error occurred | +| 529 | `overloaded_error` | The service is temporarily overloaded — retry with backoff | + +Note that `409 Conflict` carries `error.type: "invalid_request_error"` (there is no separate `conflict_error` type); inspect both the HTTP status and the `message` to distinguish conflicts from other invalid requests. + +--- + +## Rate Limits + +Managed Agents endpoints have per-organization request-per-minute (RPM) limits, separate from your [Messages API token limits](https://platform.claude.com/docs/en/api/rate-limits). Model inference inside a session still draws from your organization's standard ITPM/OTPM limits. + +| Endpoint group | Scope | RPM | Max concurrent | +|---|---|---|---| +| Create operations (Agents, Sessions, Vaults) | organization | 60 | — | +| All other operations (Agents, Sessions, Vaults) | organization | 600 | — | +| All operations (Environments) | organization | 60 | 5 | + +Files and Skills endpoints use the standard tier-based [rate limits](https://platform.claude.com/docs/en/api/rate-limits). + +When a limit is exceeded the API returns `429` with a `rate_limit_error` (see [Error Handling](#error-handling) for the response envelope) and a `retry-after` header indicating how many seconds to wait before retrying. The Anthropic SDK reads this header and retries automatically. diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-client-patterns.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-client-patterns.md new file mode 100644 index 0000000..784a601 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-client-patterns.md @@ -0,0 +1,205 @@ +# Managed Agents — Common Client Patterns + +Patterns you'll write on the client side when driving a Managed Agent session, grounded in working SDK examples. + +Code samples are TypeScript — Python and cURL follow the same shape; see `python/managed-agents/README.md` and `curl/managed-agents.md` for equivalents. + +--- + +## 1. Lossless stream reconnect + +**Problem:** SSE has no replay. If the connection drops mid-session, a naive reconnect re-opens the stream from "now" and you silently miss every event emitted in between. + +**Solution:** on reconnect, fetch the full event history via `events.list()` *before* consuming the live stream, and dedupe on event ID as the live stream catches up. + +```ts +const seenEventIds = new Set() +const stream = await client.beta.sessions.events.stream(session.id) + +// Stream is now open and buffering server-side. Read history first. +for await (const event of client.beta.sessions.events.list(session.id)) { + seenEventIds.add(event.id) + handle(event) +} + +// Tail the live stream. Dedupe only gates handle() — terminal checks must run +// even for already-seen events, or a terminal event that was in the history +// response gets skipped by `continue` and the loop never exits. +for await (const event of stream) { + if (!seenEventIds.has(event.id)) { + seenEventIds.add(event.id) + handle(event) + } + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle' && event.stop_reason.type !== 'requires_action') break +} +``` + +--- + +## 2. `processed_at` — queued vs processed + +Every event on the stream carries `processed_at` (ISO 8601). For client-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`) it's `null` when the event has been queued but not yet picked up by the agent, and populated once the agent processes it. The same event appears on the stream twice — once with `processed_at: null`, once with a timestamp. + +```ts +for await (const event of stream) { + if (event.type === 'user.message') { + if (event.processed_at == null) onQueued(event.id) + else onProcessed(event.id, event.processed_at) + } +} +``` + +Use this to drive pending → acknowledged UI state for anything you send. How you map a locally-rendered optimistic message to the server-assigned `event.id` is application-specific (typically via the return value of `events.send()` or FIFO ordering). + +--- + +## 3. Interrupt a running session + +Send `user.interrupt` as a normal event. The session keeps running until it reaches a safe boundary, then goes idle. + +```ts +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.interrupt' }], +}) + +// Drain until the session is truly done — see Pattern 5 for the full gate. +for await (const event of stream) { + if (event.type === 'session.status_terminated') break + if ( + event.type === 'session.status_idle' && + event.stop_reason.type !== 'requires_action' + ) break +} +``` + +Reference: `interrupt.ts` — sends the interrupt the moment it sees `span.model_request_start`, drains to idle, then verifies via `sessions.retrieve()`. + +--- + +## 4. `tool_confirmation` round-trip + +When the agent has `permission_policy: { type: 'always_ask' }`, any call to that tool fires an `agent.tool_use` event with `evaluated_permission === 'ask'` and the session goes idle waiting for a decision. Respond with `user.tool_confirmation`. + +```ts +for await (const event of stream) { + if (event.type === 'agent.tool_use' && event.evaluated_permission === 'ask') { + await client.beta.sessions.events.send(session.id, { + events: [{ + type: 'user.tool_confirmation', + tool_use_id: event.id, // not a toolu_ id — use event.id + result: 'allow', // or 'deny' + // deny_message: '...', // optional, only with result: 'deny' + }], + }) + } +} +``` + +Key points: +- `tool_use_id` is `event.id` (typically `sevt_...`), **not** a `toolu_...` ID. +- `result` is `'allow' | 'deny'`. Use `deny_message` to tell the model *why* you denied — it gets surfaced back to the agent. +- Multiple pending tools: respond once per `agent.tool_use` event with `evaluated_permission === 'ask'`. + +Reference: `tool-permissions.ts`. + +--- + +## 5. Correct idle-break gate + +Do not break on `session.status_idle` alone. The session goes idle transiently — e.g. between parallel tool executions, while waiting for a `user.tool_confirmation`, or while awaiting a `user.custom_tool_result`. Break when idle with a terminal `stop_reason`, or on `session.status_terminated`. + +```ts +for await (const event of stream) { + handle(event) + if (event.type === 'session.status_terminated') break + if (event.type === 'session.status_idle') { + if (event.stop_reason.type === 'requires_action') continue // waiting on you — handle it + break // end_turn or retries_exhausted — both terminal + } +} +``` + +`stop_reason.type` values on `session.status_idle`: +- `requires_action` — agent is waiting on a client-side event (tool confirmation, custom tool result). Handle it, don't break. +- `retries_exhausted` — terminal failure. Break, then check `sessions.retrieve()` for the error state. +- `end_turn` — normal completion. + +--- + +## 6. Post-idle status-write race + +The SSE stream emits `session.status_idle` slightly before the session's queryable status reflects it. Clients that break on idle and immediately call `sessions.delete()` or `sessions.archive()` will intermittently 400 with "cannot delete/archive while running." + +Poll before cleanup: + +```ts +let s +for (let i = 0; i < 10; i++) { + s = await client.beta.sessions.retrieve(session.id) + if (s.status !== 'running') break + await new Promise(r => setTimeout(r, 200)) +} +if (s?.status !== 'running') { + await client.beta.sessions.archive(session.id) +} // else: still running after 2s — don't archive, let it settle or escalate +``` + +--- + +## 7. Stream-first, then send + +Always open the stream **before** sending the kickoff event. Otherwise the agent may process the event and emit the first events before your consumer is attached, and you'll miss them. + +```ts +const stream = await client.beta.sessions.events.stream(session.id) +await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.message', content: [{ type: 'text', text: 'Hello' }] }], +}) +for await (const event of stream) { /* ... */ } +``` + +The `Promise.all([stream, send])` shape works too, but stream-first is simpler and has the same effect — the stream starts buffering the moment it's opened. + +--- + +## 8. File-mount gotchas + +**The mounted resource has a different `file_id` than the file you uploaded.** Session creation makes a session-scoped copy. + +```ts +const uploaded = await client.beta.files.upload({ file, purpose: 'agent_resource' }) +// uploaded.id → the original file +const session = await client.beta.sessions.create({ + /* ... */ + resources: [{ type: 'file', file_id: uploaded.id, mount_path: '/workspace/data.csv' }], +}) +// session.resources[0].file_id !== uploaded.id ← different IDs +``` + +Delete the original via `files.delete(uploaded.id)`; the session-scoped copy is garbage-collected with the session. `mount_path` must be absolute — see `shared/managed-agents-environments.md`. + +--- + +## 9. Keep credentials host-side via custom tools + +**Problem:** putting a third-party API key in the agent's vault or environment means the sandbox holds the secret. For keys tied to a human (Linear personal keys, `gh` CLI auth) or keys you'd rather not ship into a container, that's undesirable. + +**Solution:** expose the operation as a custom tool. The agent emits `agent.custom_tool_use`; your orchestrator executes the call with its own credentials and responds with `user.custom_tool_result`. The container never sees the key. + +```ts +// Agent template: declare the tool, no credentials +tools: [{ type: 'custom', name: 'linear_graphql', input_schema: { /* query, vars */ } }] + +// Orchestrator: handle the call with host-side creds +for await (const event of stream) { + if (event.type === 'agent.custom_tool_use' && event.name === 'linear_graphql') { + const result = await linear.request(event.input.query, event.input.vars) // host's key + await client.beta.sessions.events.send(session.id, { + events: [{ type: 'user.custom_tool_result', tool_use_id: event.id, result }], + }) + } +} +``` + +Same shape works for `gh` CLI, local eval scripts, or anything else that needs host-only auth or binaries. diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-core.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-core.md new file mode 100644 index 0000000..2eb1e47 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-core.md @@ -0,0 +1,216 @@ +# Managed Agents — Core Concepts + +## Architecture + +Managed Agents is built around four core concepts: + +| Concept | Endpoint | What it is | +|---|---|---| +| **Agent** | `/v1/agents` | A persisted, versioned object defining the agent's capabilities and persona: model, system prompt, tools, MCP servers, skills. **Must be created before starting a session.** See the Agents section below. | +| **Session** | `/v1/sessions` | A stateful interaction with an agent. References a pre-created agent by ID + an environment + initial instructions. Produces an event stream. | +| **Environment** | `/v1/environments` | A template defining the configuration for container provisioning. | +| **Container** | N/A | An isolated compute instance where the agent's **tools** execute (bash, file ops, code). The agent loop does not run here — it runs on Anthropic's orchestration layer and acts on the container via tool calls. | + +``` + ┌─────────────────────────────────────┐ + │ Anthropic orchestration layer │ +Agent (config) ───────▶│ (agent loop: Claude + tool calls) │ + └──────────────┬──────────────────────┘ + │ tool calls + ▼ +Environment (template) ──▶ Container (tool execution workspace) + │ + Session ─┤ + ├── Resources (files, repos — mounted at startup) + ├── Vault IDs (MCP credential references) + └── Conversation (event stream in/out) +``` + +> **Agent creation is a prerequisite.** Sessions reference a pre-created agent by ID — `model`/`system`/`tools` live on the agent object, never on the session. Every flow starts with `POST /v1/agents`. + +--- + +## Session Lifecycle + +``` +rescheduling → running ↔ idle → terminated +``` + +| Status | Description | +| -------------- | ------------------------------------------------------------------ | +| `idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `running` | Session has starting running, and the Agent is actively doing work. | +| `rescheduling` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `terminated` | Session has terminated, entering an irreversible and unusable state. | + +- Events can be sent when the session is `running` or `idle`. Messages are queued and processed in order. +- The agent transitions `idle → running` when it receives a new event, then back to `idle` when done. +- Errors surface as `session.error` events in the stream, not as a status value. + +### Built-in session features + +- **Context compaction** — if you approach max context, the API automatically condenses session history to keep the interaction going +- **Prompt caching** — historical repeated tokens are cached, reducing processing time and cost +- **Extended thinking** — on by default, returned as `agent.thinking` events + +### Session operations + +| Operation | Notes | +|---|---| +| List / fetch | Paginated list or single resource by ID | +| Update | Only `title` is updatable | +| Archive | Session becomes **read-only**. Not reversible. | +| Delete | Permanently deletes session, event history, container, and checkpoints. | + +--- + +## Sessions + +A session is a running agent instance inside an environment. + +### Session Object + +Key fields returned by the API: + +| Field | Type | Description | +| --------------- | -------- | --------------------------------------------------- | +| `type` | string | Always `"session"` | +| `id` | string | Unique session ID | +| `title` | string | Human-readable title | +| `status` | string | `idle`, `running`, `rescheduling`, `terminated` | +| `created_at` | string | ISO 8601 timestamp | +| `updated_at` | string | ISO 8601 timestamp | +| `archived_at` | string | ISO 8601 timestamp (nullable) | +| `environment_id` | string | Environment ID | +| `agent` | object | Agent configuration | +| `resources` | array | Attached files and repos | +| `metadata` | object | User-provided key-value pairs (max 8 keys) | +| `usage` | object | Token usage statistics | + +### Creating a session + +**A session is meaningless without an agent.** Sessions reference a pre-created agent by ID. Create the agent first via `agents.create()`, then reference it: + +```ts +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + system: "You are a helpful coding agent.", + tools: [{ type: "agent_toolset_20260401"}], + }, +); + +// 2. Start a session that references it +const session = await client.beta.sessions.create( + { + agent: agent.id, // string shorthand → latest version. Or: { type: "agent", id: agent.id, version: agent.version } + environment_id: environmentId, + title: "Hello World Session", + }, +); +``` + +**Session creation parameters:** + +| Field | Type | Required | Description | +| --------------- | -------- | -------- | ---------------------------------------------- | +| `agent` | string or object | **Yes** | String shorthand `"agent_abc123"` (latest version) or `{type: "agent", id, version}` | +| `environment_id`| string | **Yes** | Environment ID | +| `title` | string | No | Human-readable name (appears in logs/dashboards) | +| `resources` | array | No | Files or GitHub repos, mounted to the container at startup | +| `vault_ids` | array | No | Vault IDs (`vlt_*`) — MCP credentials with auto-refresh. See `shared/managed-agents-tools.md` → Vaults. | +| `metadata` | object | No | User-provided key-value pairs | + +**Agent configuration fields** (passed to `agents.create()`, not `sessions.create()`): + +| Field | Type | Required | Description | +| ------------- | -------- | -------- | ---------------------------------------------- | +| `name` | string | **Yes** | Human-readable name (1-256 chars) | +| `model` | string or object | **Yes** | Claude model ID (bare string, or `{id, speed}` object). All Claude 4.5+ models supported. | +| `system` | string | No | System prompt — defines the agent's behavior (up to 100K chars) | +| `tools` | array | No | Encompasses three kinds: (1) pre-built Claude Agent tools (`agent_toolset_20260401`), (2) MCP tools (`mcp_toolset`), and (3) custom client-side tools. Max 128. | +| `mcp_servers` | array | No | MCP server connections — standardized third-party capabilities (e.g. GitHub, Asana). Max 20, unique names. See `shared/managed-agents-tools.md` → MCP Servers. | +| `skills` | array | No | Customized "best-practices" context with progressive disclosure. Max 64. See `shared/managed-agents-tools.md` → Skills. | +| `description` | string | No | Description of the agent (up to 2048 chars) | +| `metadata` | object | No | Arbitrary key-value pairs (max 16, keys ≤64 chars, values ≤512 chars) | + +--- + +## Agents + +**This is where every Managed Agents flow begins.** The agent object is a persisted, versioned configuration — you create it once, then reference it by ID every time you start a session. No agent → no session. + +### Agent Object + +The API is **flat** — `model`, `system`, `tools` etc. are top-level fields, not wrapped in an `agent:{}` sub-object. + +| Field | Type | Required | Description | +| ------------------ | -------- | -------- | -------------------------------------------------- | +| `name` | string | Yes | Human-readable name | +| `model` | string | Yes | Claude model ID | +| `system` | string | No | System prompt | +| `tools` | array | No | Agent toolset / MCP toolset / custom tools | +| `mcp_servers` | array | No | MCP server connections | +| `skills` | array | No | Skill references (max 64) | +| `description` | string | No | Description of the agent | +| `metadata` | object | No | Arbitrary key-value pairs | + +### Lifecycle: create once, run many, update in place + +The agent is a **persistent resource**, not a per-run parameter. The intended pattern: + +``` +┌─ setup (once) ─────────┐ ┌─ runtime (every invocation) ─┐ +│ agents.create() │ │ sessions.create( │ +│ → store agent_id │ ──→ │ agent={type:..., id: ID} │ +│ in config/env/db │ │ ) │ +└────────────────────────┘ └──────────────────────────────┘ +``` + +**Anti-pattern:** calling `agents.create()` at the top of every script run. This accumulates orphaned agent objects, pays create latency on every invocation, and defeats the versioning model. If you see `agents.create()` in a function that's called per-request or per-cron-tick, that's wrong — hoist it to one-time setup and persist the ID. + +### Versioning + +Each `POST /v1/agents/{id}` (update) creates a new immutable version (numeric timestamp, e.g. `1772585501101368014`). The agent's history is append-only — you can't edit a past version. + +**Why version:** +- **Reproducibility** — pin a session to a known-good config: `{type: "agent", id, version: 3}` +- **Safe iteration** — update the agent without breaking sessions already running on the old version +- **Rollback** — if a new system prompt regresses, pin new sessions back to the prior version while you debug + +**`version` is optional.** Omit it (or use the string shorthand `agent="agent_abc123"`) to get the latest version at session-creation time. Pass it explicitly (`{type: "agent", id, version: N}`) to pin for reproducibility. + +**Getting the version to pin:** `agents.create()` and `agents.update()` both return `version` in the response. Store it alongside `agent_id`. To fetch the current latest for an existing agent: `GET /v1/agents/{id}` → `.version`. + +**When to update vs create new:** Update (`POST /v1/agents/{id}`) when it's conceptually the same agent with tweaked behavior (better prompt, extra tool). Create a new agent when it's a different persona/purpose. Rule of thumb: if you'd give it the same `name`, update. + +### Agent Endpoints + +| Operation | Method | Path | +| ---------------- | -------- | ------------------------------------- | +| Create | `POST` | `/v1/agents` | +| List | `GET` | `/v1/agents` | +| Get | `GET` | `/v1/agents/{id}` | +| Update | `POST` | `/v1/agents/{id}` | +| Archive | `POST` | `/v1/agents/{id}/archive` | + +### Using an Agent in a Session + +Reference the agent by string ID (latest version) or by object with an explicit version: + +```python +# String shorthand — uses the agent's latest version +session = client.beta.sessions.create( + agent=agent.id, + environment_id=environment_id, +) + +# Or pin to a specific version (int) +session = client.beta.sessions.create( + agent={"type": "agent", "id": agent.id, "version": agent.version}, + environment_id=environment_id, +) +``` + diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-environments.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-environments.md new file mode 100644 index 0000000..64cfefd --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-environments.md @@ -0,0 +1,202 @@ +# Managed Agents — Environments & Resources + +## Environments + +Creating a session requires an `environment_id`. Environments are **reusable configuration templates** for spinning up containers in Anthropic's infrastructure — you might create different environments for different use cases (e.g. data visualization vs web development, with different package sets). Anthropic handles scaling, container lifecycle, and work orchestration. + +**Environment names must be unique.** Creating an environment with an existing name returns 409. + +### Networking + +| Network Policy | Description | +| ------------------------------- | ------------------------------------------------------------- | +| `unrestricted` | Full egress (except legal blocklist) | +| `package_managers_and_custom` | Package managers + custom `allowed_hosts` | + +```json +{ + "networking": { + "type": "package_managers_and_custom", + "allowed_hosts": ["api.example.com"] + } +} +``` + +**MCP caveat:** If using restricted networking, make sure `allowed_hosts` includes your MCP server domains. Otherwise the container can't reach them and tools silently fail. + +### Creating an environment + +The SDK adds `managed-agents-2026-04-01` automatically. TypeScript: + +```ts +const env = await client.beta.environments.create({ + name: "my_env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, +}); +``` + +### Environment CRUD + +| Operation | Method | Path | Notes | +| ---------------- | -------- | ------------------------------------------ | ----- | +| Create | `POST` | `/v1/environments` | | +| List | `GET` | `/v1/environments` | Paginated (`limit`, `after_id`, `before_id`) | +| Get | `GET` | `/v1/environments/{id}` | | +| Update | `POST` | `/v1/environments/{id}` | Changes apply only to **new** containers; existing sessions keep their original config | +| Delete | `DELETE` | `/v1/environments/{id}` | Returns 204. | +| Archive | `POST` | `/v1/environments/{id}/archive` | Read-only. New sessions can't be created; existing ones continue. | + +--- + +## Resources + +Attach files and GitHub repositories to a session. **Session creation blocks until all resources are mounted** — the container won't go `running` until every file and repo is in place. Max **999 file resources** per session. Multiple GitHub repositories per session are supported. + +### File Uploads (input — host → agent) + +Upload a file first via the Files API, then reference by `file_id` + `mount_path`: + +```ts +// 1. Upload +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// 2. Attach as a session resource +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + resources: [ + { type: "file", file_id: file.id, mount_path: "/workspace/data.csv" } + ], +}); +``` + +**`mount_path` is required** and must be absolute. Parent directories are created automatically. Agent working directory defaults to `/workspace`. Files are mounted read-only — the agent writes modified versions to new paths. + +### Session outputs (output — agent → host) + +The agent can write files to `/mnt/session/outputs/` during a session. These are automatically captured by the Files API and can be listed and downloaded afterwards: + +```ts +// After the turn completes, list output files scoped to this session: +for await (const f of client.beta.files.list({ scope: session.id })) { + console.log(f.filename, f.size_bytes); + const resp = await client.beta.files.download(f.id); + const text = await resp.text(); +} +``` + +**Requirements:** +- The `write` tool (or `bash`) must be enabled for the agent to create output files. +- Session-scoped `files.list` / `files.download` captures outputs written to `/mnt/session/outputs/`. +- `session_id` is a query filter on `files.list` (not yet in SDK types — cast or spread through). +- There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if empty. + +This gives you a bidirectional file bridge: upload reference data in, download agent artifacts out. + +### GitHub Repositories + +Clones a GitHub repository into the session container during initialization, before the agent begins execution. The agent can read, edit, commit, and push via `bash` (`git`). Multiple repositories per session are supported — add one `resources` entry per repo. + +**Fields:** + +| Field | Required | Notes | +|---|---|---| +| `type` | ✅ | `"github_repository"` | +| `url` | ✅ | The GitHub repository URL | +| `authorization_token` | ✅ | GitHub Personal Access Token with repository access. **Never echoed in API responses.** | +| `mount_path` | ❌ | Path where the repository will be cloned. Defaults to `/workspace/`. | +| `checkout` | ❌ | `{type: "branch", name: "..."}` or `{type: "commit", sha: "..."}`. Defaults to the repo's default branch. | + +**Token permission levels** (fine-grained PATs): +- `Contents: Read` — clone only +- `Contents: Read and write` — push changes and create pull requests + +> ‼️ **To generate pull requests** you also need GitHub **MCP server** access — the `github_repository` resource gives filesystem access only. See `shared/managed-agents-tools.md` → MCP Servers. The PR workflow is: edit files in the mounted repo → push branch via `bash` → create PR via MCP `create_pull_request` tool. + +**TypeScript:** + +```ts +// 1. Create the agent — declare GitHub MCP (no auth here) +const agent = await client.beta.agents.create( + { + name: 'GitHub Agent', + model: 'claude-opus-4-6', + mcp_servers: [ + { type: 'url', name: 'github', url: 'https://api.githubcopilot.com/mcp/' }, + ], + tools: [ + { type: 'agent_toolset_20260401', default_config: { enabled: true } }, + { type: 'mcp_toolset', mcp_server_name: 'github' }, + ], + }, +); + +// 2. Start a session — attach vault for MCP auth + mount the repo +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: envId, + vault_ids: [vaultId], // vault contains the GitHub MCP OAuth credential + resources: [ + { + type: 'github_repository', + url: 'https://github.com/owner/repo', + authorization_token: process.env.GITHUB_TOKEN, // repo clone token (≠ MCP auth) + checkout: { type: 'branch', name: 'main' }, + }, + ], +}); +``` + +**Python:** + +```python +import os + +agent = client.beta.agents.create( + name="GitHub Agent", + model="claude-opus-4-6", + mcp_servers=[{ + "type": "url", + "name": "github", + "url": "https://api.githubcopilot.com/mcp/", + }], + tools=[ + {"type": "agent_toolset_20260401", "default_config": {"enabled": True}}, + {"type": "mcp_toolset", "mcp_server_name": "github"}, + ], +) + +session = client.beta.sessions.create( + agent=agent.id, + environment_id=env_id, + vault_ids=[vault_id], # vault contains the GitHub MCP OAuth credential + resources=[{ + "type": "github_repository", + "url": "https://github.com/owner/repo", + "authorization_token": os.environ["GITHUB_TOKEN"], # repo clone token (≠ MCP auth) + "checkout": {"type": "branch", "name": "main"}, + }], +) +``` + +--- + +## Files API + +Upload and manage files for use as session resources, and download files the agent wrote to `/mnt/session/outputs/`. + +| Operation | Method | Path | SDK | +| ---------------- | -------- | ------------------------------------- | --- | +| Upload | `POST` | `/v1/files` | `client.beta.files.upload({ file })` | +| List | `GET` | `/v1/files?session_id=...` | `client.beta.files.list({ session_id })` | +| Get Metadata | `GET` | `/v1/files/{id}` | `client.beta.files.retrieveMetadata(id)` | +| Download | `GET` | `/v1/files/{id}/content` | `client.beta.files.download(id)` → `Response` | +| Delete | `DELETE` | `/v1/files/{id}` | `client.beta.files.delete(id)` | + +The `session_id` filter on List scopes the results to files written to `/mnt/session/outputs/` by that session. Without the filter, you get all files uploaded to your account. diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-events.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-events.md new file mode 100644 index 0000000..5b10581 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-events.md @@ -0,0 +1,187 @@ +# Managed Agents — Events & Steering + +## Events + +### Sending Events + +Send events to a session via `POST /v1/sessions/{id}/events`. + +| Event Type | When to Send | +| ------------------------- | --------------------------------------------------- | +| `user.message` | Send a user message | +| `user.interrupt` | Interrupt the agent while it's running | +| `user.tool_confirmation` | Approve/deny a tool call (when `always_ask` policy) | +| `user.custom_tool_result` | Provide result for a custom tool call | + +### Receiving Events + +Two methods: + +1. **Streaming (SSE)**: `GET /v1/sessions/{id}/events/stream` — real-time Server-Sent Events. **Long-lived** — the server sends periodic heartbeats to keep the connection alive. +2. **Polling**: `GET /v1/sessions/{id}/events` — paginated event list (query params: `limit` default 1000, `page`). **Returns immediately** — this is a plain paginated GET, not a long-poll. + +All received events carry `id`, `type`, and `processed_at` (ISO 8601; `null` if not yet processed by the agent). + +> ⚠️ **Robust polling (raw HTTP).** If you bypass the SDK and roll your own poll loop, don't rely on `requests` or `httpx` timeouts as wall-clock caps — they're **per-chunk** read timeouts, reset every time a byte arrives. A trickling response (heartbeats, a wedged chunked-encoding body, a misbehaving proxy) can keep the call blocked indefinitely even with `timeout=(5, 60)` or `httpx.Timeout(120)`. Neither library has a "total wall-clock" timeout built in. For a hard deadline: track `time.monotonic()` at the loop level and break/cancel if a single request exceeds your budget (e.g. via a watchdog thread, or `asyncio.wait_for()` around async httpx). **Prefer the SDK** — `client.beta.sessions.events.stream()` and `client.beta.sessions.events.list()` handle timeout + retry sanely. +> +> If `GET /v1/sessions/{id}/events` (paginated) ever hangs after headers, you've likely hit `GET /v1/sessions/{id}/events` by mistake or a server-side stall — report it; don't treat it as a client-config problem. + +### Event Types (Received) + +Event types use dot notation, grouped by namespace: + +| Event Type | Description | +| --- | --- | +| `agent.message` | Agent text output | +| `agent.thinking` | Extended thinking blocks | +| `agent.tool_use` | Agent used a built-in tool (`agent_toolset_20260401`) | +| `agent.tool_result` | Result from a built-in tool | +| `agent.mcp_tool_use` | Agent used an MCP tool | +| `agent.mcp_tool_result` | Result from an MCP tool | +| `agent.custom_tool_use` | Agent invoked a custom tool — session goes idle, you respond with `user.custom_tool_result` | +| `agent.thread_context_compacted` | Conversation context was compacted | +| `session.status_idle` | Agent has finished the current task, and is awaiting input. It's either waiting for input to continue working via a `user.message` or blocked awaiting a `user.custom_tool_result` or `user.tool_confirmation`. The `stop_reason` attached contains more information about why the Agent has stopped working. | +| `session.status_running` | Session has starting running, and the Agent is actively doing work. | +| `session.status_rescheduled` | Session is (re)scheduling after a retryable error has occurred, ready to be picked up by the orchestration system. | +| `session.status_terminated` | Session has terminated, entering an irreversible and unusable state. | +| `session.error` | Error occurred during processing | +| `span.model_request_start` | Model inference started | +| `span.model_request_end` | Model inference completed | + +The stream also echoes back user-sent events (`user.message`, `user.interrupt`, `user.tool_confirmation`, `user.custom_tool_result`). + +--- + +## Steering Patterns + +Practical patterns for driving a session via the events surface. + +### Stream-first ordering + +**Open the stream before sending events.** The stream only delivers events that occur *after* it's opened — it does not replay current state or historical events. If you send a message first and open the stream second, early events (including fast status transitions) arrive buffered in a single batch and you lose the ability to react to them in real time. + +```ts +// ✅ Correct — stream and send concurrently +const [response] = await Promise.all([ + streamEvents(sessionId), // opens SSE connection + sendMessage(sessionId, text), +]); + +// ❌ Wrong — events before stream opens arrive as a single buffered batch +await sendMessage(sessionId, text); +const response = await streamEvents(sessionId); +``` + +**For full history,** use `GET /v1/sessions/{id}/events` (paginated list) — the stream only gives you live events from connection onward. + +### Reconnecting after a dropped stream + +**The SSE stream has no replay.** If your connection drops (httpx read timeout, network blip) and you reconnect, you only get events emitted *after* reconnection. Any events emitted during the gap are lost from the stream. + +**The consolidation pattern:** on every (re)connect, overlap the stream with a history fetch and dedupe by event ID: + +```python +def connect_with_consolidation(client, session_id): + # 1. Open the SSE stream first + stream = client.beta.sessions.events.stream(session_id=session_id) + + # 2. Fetch history to cover any gap + history = client.beta.sessions.events.list( + session_id=session_id, + ) + + # 3. Yield history first, then stream — dedupe by event.id + seen = set() + for ev in history.data: + seen.add(ev.id) + yield ev + for ev in stream: + if ev.id not in seen: + seen.add(ev.id) + yield ev +``` + +### Message queuing + +**You don't have to wait for a response before sending the next message.** User events are queued server-side and processed in order. This is useful for chat bridges where the user sends rapid follow-ups: + +```ts +// All three go into one session; agent processes them in order +await sendMessage(sessionId, "Summarize the README"); +await sendMessage(sessionId, "Actually also check the CONTRIBUTING guide"); +await sendMessage(sessionId, "And compare the two"); +// Stream once — agent responds to all three as a coherent turn +``` + +Events can be sent up to the Session at any time. There is no need to wait on a specific session status to enqueue new events via `client.beta.sessions.events.send()` + +### Interrupt + +An `interrupt` event **jumps the queue** (ahead of any pending user messages) and forces the session into `idle`. Use this for "stop" / "nevermind" / "cancel" commands: + +```ts +await client.beta.sessions.events.send(sessionId, { + events: [{ type: 'interrupt' }], +}); +``` + +The agent stops mid-task. It does not see the interrupt as a message — it just halts. Send a follow-up `user` event to explain what to do instead. + +> **Note**: Interrupt events may have empty IDs in the current implementation. When troubleshooting, use the `processed_at` timestamp along with surrounding event IDs. + +### Event payloads + +some events carry useful metadata beyond the status change itself: + +`session.status_idle` — includes a `stop_reason` field which elaborates on why the session stopped and what type of further action is required by the user. +```json +{ + "id": "sevt_456", + "processed_at": "2026-04-07T04:27:43.197Z", + "stop_reason": { + "event_ids": [ + "sevt_123" + ], + "type": "requires_action" + }, + "type": "status_idle" +} +``` + +`span.model_request_end` contains a `model_usage` field for cost tracking and efficiency analysis: + +```json +{ + "type": "span.model_request_end", + "id": "sevt_456", + "is_error": false, + "model_request_start_id": "sevt_123", + "model_usage": { + "cache_creation_input_tokens": 0, + "cache_read_input_tokens": 6656, + "input_tokens": 3571, + "output_tokens": 727 + }, + "processed_at": "2026-04-07T04:11:32.189Z" +} +``` + +**`agent.thread_context_compacted`** — emitted when the conversation history was summarized to fit context. Includes `pre_compaction_tokens` so you know how much was squeezed: + +```json +{ + "id": "sevt_abc123", + "processed_at": "2026-03-24T14:05:15.787Z", + "type": "agent.thread_context_compacted" +} +``` + +### Archive + +When done with a session, archive it to free resources: + +```ts +await client.beta.sessions.archive(sessionId); +``` + + diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-onboarding.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-onboarding.md new file mode 100644 index 0000000..9ee9501 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-onboarding.md @@ -0,0 +1,114 @@ +# Managed Agents — Onboarding Flow + +> **Invoked via `/claude-api managed-agents-onboard`?** You're in the right place. Run the interview below — don't summarize it back to the user, ask the questions. + +Use this when a user wants to set up a Managed Agent from scratch. Three steps: **branch on know-vs-explore → configure the template → set up the session**. End by emitting working code. + +> Read `shared/managed-agents-core.md` alongside this — it has full detail for each knob. This doc is the interview script, not the reference. + +--- + +Claude Managed Agents is a hosted agent: Anthropic runs the agent loop on its orchestration layer and provisions a sandboxed container per session where the agent's tools execute. You supply the agent config and the environment config; the harness — event stream, sandbox orchestration, prompt caching, context compaction, and extended thinking — is handled for you. + +**What you supply:** +- **An agent config** — tools, skills, model, system prompt. Reusable and versioned. +- **An environment config** — the sandbox your agent's tools execute in (networking, packages). Reusable across agents. + +Each run of the agent is a **session**. + +--- + +## 1. Know or explore? + +Ask the user: + +> Do you already know the agent you want to build, or would you like to explore some common patterns first? + +### Explore path — show the patterns + +Four shapes, same runtime code path (`sessions.create()` → `sessions.events.send()` → stream). Only the trigger and sink differ. + +| Pattern | Trigger | Example | +|---|---|---| +| Event-triggered | Webhook | GitHub PR push → CMA (GitHub tool) → Slack | # <------ MC maybe delete? +| Scheduled | Cron | Daily brief: browser + GitHub + Jira → CMA → Slack | # <------ MC maybe delete? +| Fire-and-forget PR | Human | Slack slash-command → CMA (GitHub tool) → PR passing CI | +| Research + dashboard | Human | Topic → CMA (web search + `frontend-design` skill) → HTML dashboard | + +Ask which shape fits, then continue with the Know path using it as the reference. + +### Know path — configure template + +Three rounds. Batch the questions in each round; don't ask them one at a time. + +**Round A — Tools.** Start here; it's the most concrete part. Three types; ask which the user wants (any combination): + +| Type | What it is | How to guide | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Ready-to-use: `bash`, `read`, `write`, `edit`, `glob`, `grep`, `web_fetch`, `web_search`. Enable all at once, or individually via `enabled: true/false`. | Recommend enabling the full toolset. List the 8 tools so the user knows what they're getting. Full detail: `shared/managed-agents-tools.md` → Agent Toolset. | +| **MCP tools** | Third-party integrations (GitHub, Linear, Asana, etc.) via `mcp_toolset`. Credentials live in a vault, not inline. | Ask which services. For each, walk through MCP server URL + vault credentials. Full detail: `shared/managed-agents-tools.md` → MCP Servers + Vaults. | +| **Custom tools** | The user's own app handles these tool calls — agent fires `agent.custom_tool_use`, the app sends a result message back. | Ask for each tool: name, description, input schema. The app code that handles the event is *their* code — don't generate it. Full detail: `shared/managed-agents-tools.md` → Custom Tools. | + +**Round B — Skills, files, and repos.** What the agent has on hand when it starts. + +*Skills* — two types; both work the same way — Claude auto-uses them when relevant. Max 64 per agent. +- [ ] **Pre-built Agent Skills**: `xlsx`, `docx`, `pptx`, `pdf`. Reference by name. +- [ ] **Custom Skills**: skills uploaded to the user's org via the Skills API. Reference by `skill_id` + optional `version`. If the skill doesn't exist yet, walk the user through `POST /v1/skills` + `POST /v1/skills/{id}/versions` (beta header `skills-2025-10-02`). Full detail: `shared/managed-agents-tools.md` → Skills + Skills API. + +*GitHub repositories* — any repos the agent needs on-disk? For each: +- [ ] Repo URL (`https://github.com/org/repo`) +- [ ] `authorization_token` (PAT or GitHub App token scoped to the repo) +- [ ] Optional `mount_path` (defaults to `/workspace/`) and `checkout` (branch or SHA) + +Emit as `resources: [{type: "github_repository", url, authorization_token, ...}]`. Full detail: `shared/managed-agents-environments.md` → GitHub Repositories. + +> ‼️ **PR creation needs the GitHub MCP server too.** `github_repository` gives filesystem access only — to open PRs, also attach the GitHub MCP server in Round A and credential it via a vault. The workflow is: edit files in the mounted repo → push branch via `bash` → create PR via the MCP `create_pull_request` tool. + +*Files* — any local files to seed the session with? For each: +- [ ] Upload via the Files API → persist `file_id` +- [ ] Choose a `mount_path` — absolute, e.g. `/workspace/data.csv` (parents auto-created; files mount read-only) + +Emit as `resources: [{type: "file", file_id, mount_path}]`. Max 999 file resources. Agent working directory defaults to `/workspace`. Full detail: `shared/managed-agents-environments.md` → Files API. + +**Round C — Environment + identity:** +- [ ] Networking: unrestricted internet from the container, or lock egress to specific hosts? (If locked, MCP server domains must be in `allowed_hosts` or tools silently fail.) +- [ ] Name? +- [ ] Job (one or two sentences — becomes the system prompt)? +- [ ] Model? (default `claude-opus-4-6`) + +--- + +## 2. Set up the session + +Per-run. Points at the agent + environment, attaches credentials, kicks off. + +**Vault credentials** (if the agent declared MCP servers): +- [ ] Existing vault, or create one? (`client.beta.vaults.create()` + `vaults.credentials.create()`) + +Credentials are write-only, matched to MCP servers by URL, auto-refreshed. See `shared/managed-agents-tools.md` → Vaults. + +**Kickoff:** +- [ ] First message to the agent? + +Session creation blocks until all resources mount. Open the event stream before sending the kickoff. Stream is SSE; break on `session.status_terminated`, or on `session.status_idle` with a terminal `stop_reason` — i.e. anything except `requires_action`, which fires transiently while the session waits on a tool confirmation or custom-tool result (see `shared/managed-agents-client-patterns.md` Pattern 5). Usage lands on `span.model_request_end`. Agent-written artifacts end up in `/mnt/session/outputs/` — download via `files.list({scope: session_id})`. + +--- + +## 3. Emit the code + +Go straight from the last interview answer to the code — no preamble about the setup-vs-runtime split, no "the critical thing to internalize…", no lecture about `agents.create()` being one-time. The two-block structure below already shows that; don't narrate it. Generate **two clearly-separated blocks** per language detected (Python/TS/cURL — see SKILL.md → Language Detection): + +**Block 1 — Setup (run once, store the IDs):** +1. `environments.create()` → persist `env_id` +2. `agents.create()` with everything from §Round A–C → persist `agent_id` and `agent_version` + +Label: `# ONE-TIME SETUP — run once, save the IDs to config/.env` + +**Block 2 — Runtime (run on every invocation):** +1. Load `env_id` + `agent_id` from config/env +2. `sessions.create(agent=AGENT_ID, environment_id=ENV_ID, resources=[...], vault_ids=[...])` +3. Open stream, `events.send()` the kickoff, loop until `session.status_terminated` or `session.status_idle && stop_reason.type !== 'requires_action'` (see `shared/managed-agents-client-patterns.md` Pattern 5 for the full gate — do not break on bare `session.status_idle`) + +> ⚠️ **Never emit `agents.create()` and `sessions.create()` in the same unguarded block.** That teaches the user to create a new agent on every run — the #1 anti-pattern. If they need a single script, wrap agent creation in `if not os.getenv("AGENT_ID"):`. + +Pull exact syntax from `python/managed-agents/README.md`, `typescript/managed-agents/README.md`, or `curl/managed-agents.md`. Don't invent field names. diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-overview.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-overview.md new file mode 100644 index 0000000..bbb0a89 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-overview.md @@ -0,0 +1,61 @@ +# Managed Agents — Overview + +Managed Agents provisions a container per session as the agent's workspace. The agent loop runs on Anthropic's orchestration layer; the container is where the agent's *tools* execute — bash commands, file operations, code. You create a persisted **Agent** config (model, system prompt, tools, MCP servers, skills), then start **Sessions** that reference it. The session streams events back to you; you send user messages and tool results in. + +## ⚠️ THE MANDATORY FLOW: Agent (once) → Session (every run) + +**Why agents are separate objects: versioning.** An agent is a persisted, versioned config — every update creates a new immutable version, and sessions pin to a version at creation time. This lets you iterate on the agent (tweak the prompt, add a tool) without breaking sessions already running, roll back if a change regresses, and A/B test versions side-by-side. None of that works if you `agents.create()` fresh on every run. + +Every session references a pre-created `/v1/agents` object. Create the agent once, store the ID, and reuse it across runs. + +| Step | Call | Frequency | +|---|---|---| +| 1 | `POST /v1/agents` — `model`, `system`, `tools`, `mcp_servers`, `skills` live here | **ONCE.** Store `agent.id` **and** `agent.version`. | +| 2 | `POST /v1/sessions` — `agent: "agent_abc123"` or `{type: "agent", id, version}` | **Every run.** String shorthand uses latest version. | + +If you're about to write `sessions.create()` with `model`, `system`, or `tools` on the session body — **stop**. Those fields live on `agents.create()`. The session takes a *pointer* only. + +**When generating code, separate setup from runtime.** `agents.create()` belongs in a setup script (or a guarded `if agent_id is None:` block), not at the top of the hot path. If the user's code calls `agents.create()` on every invocation, they're accumulating orphaned agents and paying the create latency for nothing. The correct shape is: create once → persist the ID (config file, env var, secrets manager) → every run loads the ID and calls `sessions.create()`. + +**To change the agent's behavior, use `POST /v1/agents/{id}` — don't create a new one.** Each update bumps the version; running sessions keep their pinned version, new sessions get the latest (or pin explicitly via `{type: "agent", id, version}`). See `shared/managed-agents-core.md` → Agents → Versioning. + +## Beta Headers + +Managed Agents is in beta. The SDK sets required beta headers automatically: + +| Beta Header | What it enables | +| ------------------------------ | ---------------------------------------------------- | +| `managed-agents-2026-04-01` | Agents, Environments, Sessions, Events, Session Resources, Vaults, Credentials | +| `skills-2025-10-02` | Skills API (for managing custom skill definitions) | +| `files-api-2025-04-14` | Files API for file uploads | + +**Note: do not intermix beta headers** — If you need to upload a skill or file via the Skills API or Files API you will need to use the appropriate beta header as listed above. However, you do NOT need to inlude either the Skills or Files beta header when using any of the Managed Agents endpints listed in row 1 above. Do NOT include intermix beta headers and prefer to use the Skills or Files beta headers when using their specific endpoints. + + +## Reading Guide + +| User wants to... | Read these files | +| -------------------------------------- | ------------------------------------------------------- | +| **Get started from scratch / "help me set up an agent"** | `shared/managed-agents-onboarding.md` — guided interview (WHERE→WHO→WHAT→WATCH), then emit code | +| Understand how the API works | `shared/managed-agents-core.md` | +| See the full endpoint reference | `shared/managed-agents-api-reference.md` | +| **Create an agent** (required first step) | `shared/managed-agents-core.md` (Agents section) + language file | +| Update/version an agent | `shared/managed-agents-core.md` (Agents → Versioning) — update, don't re-create | +| Create a session | `shared/managed-agents-core.md` + `{lang}/managed-agents/README.md` | +| Configure tools and permissions | `shared/managed-agents-tools.md` | +| Set up MCP servers | `shared/managed-agents-tools.md` (MCP Servers section) | +| Stream events / handle tool_use | `shared/managed-agents-events.md` + language file | +| Set up environments | `shared/managed-agents-environments.md` + language file | +| Upload files / attach repos | `shared/managed-agents-environments.md` (Resources) | +| Store MCP credentials | `shared/managed-agents-tools.md` (Vaults section) | + +## Common Pitfalls + +- **Agent FIRST, then session — NO EXCEPTIONS** — the session's `agent` field accepts **only** a string ID or `{type: "agent", id, version}`. `model`, `system`, `tools`, `mcp_servers`, `skills` are **top-level fields on `POST /v1/agents`**, never on `sessions.create()`. If the user hasn't created an agent, that is step zero of every example. +- **Agent ONCE, not every run** — `agents.create()` is a setup step. Store the returned `agent_id` and reuse it; don't call `agents.create()` at the top of your hot path. If the agent's config needs to change, `POST /v1/agents/{id}` — each update creates a new version, and sessions can pin to a specific version for reproducibility. +- **MCP auth goes through vaults** — the agent's `mcp_servers` array declares `{type, name, url}` only (no auth). Credentials live in vaults (`client.beta.vaults.credentials.create`) and attach to sessions via `vault_ids`. Anthropic auto-refreshes OAuth tokens using the stored refresh token. +- **Stream to get events** — `GET /v1/sessions/{id}/events/stream` is the primary way to receive agent output in real-time. +- **SSE stream has no replay — reconnect with consolidation** — if the stream drops while a `agent.tool_use`, `agent.mcp_tool_use`, or `agent.custom_tool_use` is pending resolution (`user.tool_confirmation` for the first two, `user.custom_tool_result` for the last one), the session deadlocks (client disconnects → session idles → reconnect happens → no client resolution happens). On every (re)connect: open stream with `GET /v1/sessions/{id}/events/stream` , fetch `GET /v1/sessions/{id}/events`, dedupe by event ID, then proceed. See `shared/managed-agents-events.md` → Reconnecting after a dropped stream. +- **Don't trust HTTP-library timeouts as wall-clock caps** — `requests` `timeout=(c, r)` and `httpx.Timeout(n)` are *per-chunk* read timeouts; they reset every byte, so a trickling connection can block indefinitely. For a hard deadline on raw-HTTP polling, track `time.monotonic()` at the loop level and bail explicitly. Prefer the SDK's `sessions.events.stream()` / `session.events.list()` over hand-rolled HTTP. See `shared/managed-agents-events.md` → Receiving Events. +- **Messages queue** — you can send events while the session is `running` or `idle`; they're processed in order. No need to wait for a response before sending the next message. +- **Cloud environments only** — `config.type: "cloud"` is the only supported environment type. diff --git a/junie/versions/2285.4/skills/claude-api/shared/managed-agents-tools.md b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-tools.md new file mode 100644 index 0000000..cce75c9 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/managed-agents-tools.md @@ -0,0 +1,301 @@ +# Managed Agents — Tools & Skills + +## Tools + +### Server tools vs client tools + +| Type | Who runs it | How it works | +|---|---|---| +| **Prebuilt Claude Agent tools** (`agent_toolset_20260401`) | Anthropic, on the session's container | File ops, bash, web search, etc. Enable all at once or configure individually with `enabled: true/false`. | +| **MCP tools** (`mcp_toolset`) | Anthropic, on the session's container | Capabilities exposed by connected MCP servers. Grant access per-server via the toolset. | +| **Custom tools** | **You** — your application handles the call and returns results | Agent emits a `agent.custom_tool_use` event, session goes `idle`, you send back a `user.custom_tool_result` event. | + +**Recommendation:** Enable all prebuilt tools via `agent_toolset_20260401`, then disable individually as needed. + +**Versioning:** The toolset is a versioned, static resource. When underlying tools change, a new toolset version is created (hence `_20260401`) so you always know exactly what you're getting. + +### Agent Toolset + +The `agent_toolset_20260401` provides these built-in tools: + +| Tool | Description | +| ---------------------- | ---------------------------------------- | +| `bash` | Execute bash commands in a shell session | +| `read` | Read a file from the local filesystem, including text, images, PDFs, and Jupyter notebooks | +| `write` | Write a file to the local filesystem | +| `edit` | Perform string replacement in a file | +| `glob` | Fast file pattern matching using glob patterns | +| `grep` | Text search using regex patterns | +| `web_fetch` | Fetch content from a URL | +| `web_search` | Search the web for information | + +Enable the full toolset: + +```json +{ + "tools": [ + { "type": "agent_toolset_20260401" } + ] +} +``` + +### Per-Tool Configuration + +Override defaults for individual tools. This example enables everything except bash: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": true }, + "configs": [ + { "name": "bash", "enabled": false } + ] + } + ] +} +``` + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"agent_toolset_20260401"` | +| `default_config` | ❌ | Applied to all tools. `{ "enabled": bool, "permission_policy": {...} }` | +| `configs` | ❌ | Per-tool overrides: `[{ "name": "...", "enabled": bool, "permission_policy": {...} }]` | + +### Permission Policies + +Control when server-executed tools (agent toolset + MCP) run automatically vs wait for approval. Does not apply to custom tools. + +| Policy | Behavior | +|---|---| +| `always_allow` | Tool executes automatically (default) | +| `always_ask` | Session emits `session.status_idle` and pauses until you send a `tool_confirmation` event | + +```json +{ + "type": "agent_toolset_20260401", + "default_config": { + "enabled": true, + "permission_policy": { "type": "always_allow" } + }, + "configs": [ + { "name": "bash", "permission_policy": { "type": "always_ask" } } + ] +} +``` + +**Responding to `always_ask`:** Send a `user.tool_confirmation` event with `tool_use_id` from the triggering `agent_tool_use`/`mcp_tool_use` event: + +```json +{ "type": "tool_confirmation", "tool_use_id": "sevt_abc123", "result": "allow" } +{ "type": "tool_confirmation", "tool_use_id": "sevt_def456", "result": "deny", "message": "Read .env.example instead" } +``` + +The optional `message` on a deny is delivered to the agent so it can adjust its approach. + +To enable only specific tools, flip the default off and opt-in per tool: + +```json +{ + "tools": [ + { + "type": "agent_toolset_20260401", + "default_config": { "enabled": false }, + "configs": [ + { "name": "bash", "enabled": true }, + { "name": "read", "enabled": true } + ] + } + ] +} +``` + +### Custom Tools (Client-Side) + +Custom tools are executed by **your application**, not Anthropic. The flow: + +1. Agent decides to use the tool → session emits a `agent.custom_tool_use` event with inputs +2. Session goes `idle` waiting for you +3. Your application executes the tool +4. You send back a `user.custom_tool_result` event with the output +5. Session resumes `running` + +No permission policy needed — you're the one executing. + +```json +{ + "tools": [ + { + "type": "custom", + "name": "get_weather", + "description": "Fetch current weather for a city.", + "input_schema": { + "type": "object", + "properties": { + "city": { "type": "string", "description": "City name" } + }, + "required": ["city"] + } + } + ] +} +``` + +### MCP Servers + +MCP (Model Context Protocol) servers expose standardized third-party capabilities (e.g. Asana, GitHub, Linear). **Configuration is split across agent and vault:** + +1. **Agent creation** declares which servers to connect to (`type`, `name`, `url` — no auth). The agent's `mcp_servers` array has no auth field. +2. **Vault** stores the OAuth credentials. Attach via `vault_ids` on session create. + +This keeps secrets out of reusable agent definitions. Each vault credential is tied to one MCP server URL; Anthropic matches credentials to servers by URL. + +**Agent side — declare servers (no auth):** + +| Field | Required | Description | +|---|---|---| +| `type` | ✅ | `"url"` | +| `name` | ✅ | Unique name — referenced by `mcp_toolset.mcp_server_name` | +| `url` | ✅ | The MCP server's endpoint URL (Streamable HTTP transport) | + +```json +{ + "mcp_servers": [ + { "type": "url", "name": "linear", "url": "https://mcp.linear.app/mcp" } + ], + "tools": [ + { "type": "mcp_toolset", "mcp_server_name": "linear" } + ] +} +``` + +**Session side — attach vault:** + +```json +{ + "agent": "agent_abc123", + "environment_id": "env_abc123", + "vault_ids": ["vlt_abc123"] +} +``` + +> 💡 **Per-tool enablement (empirical):** `mcp_toolset` has been observed accepting `default_config: {enabled: false}` + `configs: [{name, enabled: true}]` for an allowlist pattern. The API ref shows only the minimal `{type, mcp_server_name}` form. + +> ⚠️ **MCP auth tokens ≠ REST API tokens.** Hosted MCP servers (`mcp.notion.com`, `mcp.linear.app`, etc.) typically require **OAuth bearer tokens**, not the service's native API keys. A Notion `ntn_` integration token authenticates against Notion's REST API but will **not** work as a vault credential for the Notion MCP server. These are different auth systems. + +### Vaults — the MCP credential store + +**Vaults** store OAuth credentials (access token + refresh token) that Anthropic auto-refreshes on your behalf via standard OAuth 2.0 `refresh_token` grant. This is the only way to authenticate MCP servers in the launch SDK. + +> Formerly known internally as TATs (Tool/Tenant Access Tokens). + +**Flow:** + +1. Create a vault (`client.beta.vaults.create(...)`) — one per tenant/user, or one shared, depending on your model +2. Add MCP credentials to it (`client.beta.vaults.credentials.create(...)`) — each credential is tied to one MCP server URL +3. Reference the vault on session create via `vault_ids: ["vlt_..."]` +4. Anthropic auto-refreshes tokens before they expire; the agent uses the current access token when calling MCP tools + +**Credential shape**: + +```json +{ + "display_name": "Notion (workspace-foo)", + "auth": { + "type": "mcp_oauth", + "mcp_server_url": "https://mcp.notion.com/mcp", + "access_token": "", + "expires_at": "2026-04-02T14:00:00Z", + "refresh": { + "refresh_token": "", + "client_id": "", + "token_endpoint": "https://api.notion.com/v1/oauth/token", + "token_endpoint_auth": { "type": "none" } + } + } +} +``` + +The `refresh` block is what enables auto-refresh — `token_endpoint` is where Anthropic posts the `refresh_token` grant. `token_endpoint_auth` is a discriminated union: + +| `type` | Shape | Use when | +|---|---|---| +| `"none"` | `{type: "none"}` | Public OAuth client (no secret) | +| `"client_secret_basic"` | `{type: "client_secret_basic", client_secret: "..."}` | Confidential client, secret via HTTP Basic auth | +| `"client_secret_post"` | `{type: "client_secret_post", client_secret: "..."}` | Confidential client, secret in request body | + +Omit `refresh` entirely if you only have an access token with no refresh capability — it'll work until it expires, then the agent loses access. + +> 💡 **Getting an OAuth token.** How you obtain the initial access and refresh tokens depends on the MCP server — consult its documentation. Once you have them, store them in a vault credential using the shape above; Anthropic auto-refreshes via the `refresh.token_endpoint` from there. + +**Scoping:** Vaults are workspace-scoped. Anyone with developer+ role in the API workspace can create, read (metadata only — secrets are write-only), and attach vaults. `vault_ids` can be set at session **create** time but not via session update (the SDK docstring says "Not yet supported; requests setting this field are rejected"). + +--- + +## Skills + +Skills are reusable, filesystem-based resources that provide your agent with domain-specific expertise: workflows, context, and best practices that transform general-purpose agents into specialists. Unlike prompts (conversation-level instructions for one-off tasks), skills load on-demand and eliminate the need to repeatedly provide the same guidance across multiple conversations. + +Two types — both work the same way; the agent automatically uses them when relevant to the task at hand: + +| Type | What it is | +|---|---| +| **Pre-built Anthropic skills** | Common document tasks (PowerPoint, Excel, Word, PDF). Reference by name (e.g. `xlsx`). | +| **Custom skills** | Skills you've created in your organization via the Skills API. Reference by `skill_id` + optional `version`. | + +**Max 64 skills per agent.** Agent creation uses `managed-agents-2026-04-01`; the separate Skills API (for managing custom skill definitions) uses `skills-2025-10-02`. + +### Enabling skills on a session + +Skills are attached to the **agent** definition via `agents.create()`: + +```ts +const agent = await client.beta.agents.create( + { + name: "Financial Agent", + model: "claude-opus-4-6", + system: "You are a financial analysis agent.", + skills: [ + { type: "anthropic", skill_id: "xlsx" }, + { type: "custom", skill_id: "skill_abc123", version: "latest" }, + ], + } +); +``` + +Python: + +```python +agent = client.beta.agents.create( + name="Financial Agent", + model="claude-opus-4-6", + system="You are a financial analysis agent.", + skills=[ + {"type": "anthropic", "skill_id": "xlsx"}, + {"type": "custom", "skill_id": "skill_abc123", "version": "latest"}, + ] +) +``` + +**Skill reference fields:** + +| Field | Anthropic skill | Custom skill | +|---|---|---| +| `type` | `"anthropic"` | `"custom"` | +| `skill_id` | Skill name (e.g. `"xlsx"`, `"docx"`, `"pptx"`, `"pdf"`) | Skill ID from Skills API (e.g. `"skill_abc123"`) | +| `version` | — | `"latest"` or a specific version number | + +### Skills API + +| Operation | Method | Path | +| --------------------- | -------- | ----------------------------------------------- | +| Create Skill | `POST` | `/v1/skills` | +| List Skills | `GET` | `/v1/skills` | +| Get Skill | `GET` | `/v1/skills/{id}` | +| Delete Skill | `DELETE` | `/v1/skills/{id}` | +| Create Version | `POST` | `/v1/skills/{id}/versions` | +| List Versions | `GET` | `/v1/skills/{id}/versions` | +| Get Version | `GET` | `/v1/skills/{id}/versions/{version}` | +| Delete Version | `DELETE` | `/v1/skills/{id}/versions/{version}` | + diff --git a/junie/versions/2285.4/skills/claude-api/shared/models.md b/junie/versions/2285.4/skills/claude-api/shared/models.md new file mode 100644 index 0000000..6344d60 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/models.md @@ -0,0 +1,119 @@ +# Claude Model Catalog + +**Only use exact model IDs listed in this file.** Never guess or construct model IDs — incorrect IDs will cause API errors. Use aliases wherever available. For the latest information, WebFetch the Models Overview URL in `shared/live-sources.md`, or query the Models API directly (see Programmatic Model Discovery below). + +## Programmatic Model Discovery + +For **live** capability data — context window, max output tokens, feature support (thinking, vision, effort, structured outputs, etc.) — query the Models API instead of relying on the cached tables below. Use this when the user asks "what's the context window for X", "does model X support vision/thinking/effort", "which models support feature Y", or wants to select a model by capability at runtime. + +```python +m = client.models.retrieve("claude-opus-4-6") +m.id # "claude-opus-4-6" +m.display_name # "Claude Opus 4.6" +m.max_input_tokens # context window (int) +m.max_tokens # max output tokens (int) + +# capabilities is an untyped nested dict — bracket access, check ["supported"] at the leaf +caps = m.capabilities +caps["image_input"]["supported"] # vision +caps["thinking"]["types"]["adaptive"]["supported"] # adaptive thinking +caps["effort"]["max"]["supported"] # effort: max (also low/medium/high) +caps["structured_outputs"]["supported"] +caps["context_management"]["compact_20260112"]["supported"] + +# filter across all models — iterate the page object directly (auto-paginates); do NOT use .data +[m for m in client.models.list() + if m.capabilities["thinking"]["types"]["adaptive"]["supported"] + and m.max_input_tokens >= 200_000] +``` + +Top-level fields (`id`, `display_name`, `max_input_tokens`, `max_tokens`) are typed attributes. `capabilities` is a dict — use bracket access, not attribute access. The API returns the full capability tree for every model with `supported: true/false` at each leaf, so bracket chains are safe without `.get()` guards. TypeScript SDK: same method names, also auto-paginates on iteration. + +### Raw HTTP + +```bash +curl https://api.anthropic.com/v1/models/claude-opus-4-6 \ + -H "x-api-key: $ANTHROPIC_API_KEY" \ + -H "anthropic-version: 2023-06-01" +``` + +```json +{ + "id": "claude-opus-4-6", + "display_name": "Claude Opus 4.6", + "max_input_tokens": 1000000, + "max_tokens": 128000, + "capabilities": { + "image_input": {"supported": true}, + "structured_outputs": {"supported": true}, + "thinking": {"supported": true, "types": {"enabled": {"supported": true}, "adaptive": {"supported": true}}}, + "effort": {"supported": true, "low": {"supported": true}, …, "max": {"supported": true}}, + … + } +} +``` + +## Current Models (recommended) + +| Friendly Name | Alias (use this) | Full ID | Context | Max Output | Status | +|-------------------|---------------------|-------------------------------|----------------|------------|--------| +| Claude Opus 4.6 | `claude-opus-4-6` | — | 200K (1M beta) | 128K | Active | +| Claude Sonnet 4.6 | `claude-sonnet-4-6` | - | 200K (1M beta) | 64K | Active | +| Claude Haiku 4.5 | `claude-haiku-4-5` | `claude-haiku-4-5-20251001` | 200K | 64K | Active | + +### Model Descriptions + +- **Claude Opus 4.6** — Our most intelligent model for building agents and coding. Supports adaptive thinking (recommended), 128K max output tokens (requires streaming for large outputs). 1M context window available in beta via `context-1m-2025-08-07` header. +- **Claude Sonnet 4.6** — Our best combination of speed and intelligence. Supports adaptive thinking (recommended). 1M context window available in beta via `context-1m-2025-08-07` header. 64K max output tokens. +- **Claude Haiku 4.5** — Fastest and most cost-effective model for simple tasks. + +## Legacy Models (still active) + +| Friendly Name | Alias (use this) | Full ID | Status | +|-------------------|---------------------|-------------------------------|--------| +| Claude Opus 4.5 | `claude-opus-4-5` | `claude-opus-4-5-20251101` | Active | +| Claude Opus 4.1 | `claude-opus-4-1` | `claude-opus-4-1-20250805` | Active | +| Claude Sonnet 4.5 | `claude-sonnet-4-5` | `claude-sonnet-4-5-20250929` | Active | +| Claude Sonnet 4 | `claude-sonnet-4-0` | `claude-sonnet-4-20250514` | Active | +| Claude Opus 4 | `claude-opus-4-0` | `claude-opus-4-20250514` | Active | + +## Deprecated Models (retiring soon) + +| Friendly Name | Alias (use this) | Full ID | Status | Retires | +|-------------------|---------------------|-------------------------------|------------|--------------| +| Claude Haiku 3 | — | `claude-3-haiku-20240307` | Deprecated | Apr 19, 2026 | + +## Retired Models (no longer available) + +| Friendly Name | Full ID | Retired | +|-------------------|-------------------------------|-------------| +| Claude Sonnet 3.7 | `claude-3-7-sonnet-20250219` | Feb 19, 2026 | +| Claude Haiku 3.5 | `claude-3-5-haiku-20241022` | Feb 19, 2026 | +| Claude Opus 3 | `claude-3-opus-20240229` | Jan 5, 2026 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20241022` | Oct 28, 2025 | +| Claude Sonnet 3.5 | `claude-3-5-sonnet-20240620` | Oct 28, 2025 | +| Claude Sonnet 3 | `claude-3-sonnet-20240229` | Jul 21, 2025 | +| Claude 2.1 | `claude-2.1` | Jul 21, 2025 | +| Claude 2.0 | `claude-2.0` | Jul 21, 2025 | + +## Resolving User Requests + +When a user asks for a model by name, use this table to find the correct model ID: + +| User says... | Use this model ID | +|-------------------------------------------|--------------------------------| +| "opus", "most powerful" | `claude-opus-4-6` | +| "opus 4.6" | `claude-opus-4-6` | +| "opus 4.5" | `claude-opus-4-5` | +| "opus 4.1" | `claude-opus-4-1` | +| "opus 4", "opus 4.0" | `claude-opus-4-0` | +| "sonnet", "balanced" | `claude-sonnet-4-6` | +| "sonnet 4.6" | `claude-sonnet-4-6` | +| "sonnet 4.5" | `claude-sonnet-4-5` | +| "sonnet 4", "sonnet 4.0" | `claude-sonnet-4-0` | +| "sonnet 3.7" | Retired — suggest `claude-sonnet-4-5` | +| "sonnet 3.5" | Retired — suggest `claude-sonnet-4-5` | +| "haiku", "fast", "cheap" | `claude-haiku-4-5` | +| "haiku 4.5" | `claude-haiku-4-5` | +| "haiku 3.5" | Retired — suggest `claude-haiku-4-5` | +| "haiku 3" | Deprecated — suggest `claude-haiku-4-5` | diff --git a/junie/versions/2285.4/skills/claude-api/shared/prompt-caching.md b/junie/versions/2285.4/skills/claude-api/shared/prompt-caching.md new file mode 100644 index 0000000..2bd9bca --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/prompt-caching.md @@ -0,0 +1,171 @@ +# Prompt Caching — Design & Optimization + +This file covers how to design prompt-building code for effective caching. For language-specific syntax, see the `## Prompt Caching` section in each language's README or single-file doc. + +## The one invariant everything follows from + +**Prompt caching is a prefix match. Any change anywhere in the prefix invalidates everything after it.** + +The cache key is derived from the exact bytes of the rendered prompt up to each `cache_control` breakpoint. A single byte difference at position N — a timestamp, a reordered JSON key, a different tool in the list — invalidates the cache for all breakpoints at positions ≥ N. + +Render order is: `tools` → `system` → `messages`. A breakpoint on the last system block caches both tools and system together. + +Design the prompt-building path around this constraint. Get the ordering right and most caching works for free. Get it wrong and no amount of `cache_control` markers will help. + +--- + +## Workflow for optimizing existing code + +When asked to add or optimize caching: + +1. **Trace the prompt assembly path.** Find where `system`, `tools`, and `messages` are constructed. Identify every input that flows into them. +2. **Classify each input by stability:** + - Never changes → belongs early in the prompt, before any breakpoint + - Changes per-session → belongs after the global prefix, cache per-session + - Changes per-turn → belongs at the end, after the last breakpoint + - Changes per-request (timestamps, UUIDs, random IDs) → **eliminate or move to the very end** +3. **Check rendered order matches stability order.** Stable content must physically precede volatile content. If a timestamp is interpolated into the system prompt header, everything after it is uncacheable regardless of markers. +4. **Place breakpoints at stability boundaries.** See placement patterns below. +5. **Audit for silent invalidators.** See anti-patterns table. + +--- + +## Placement patterns + +### Large system prompt shared across many requests + +Put a breakpoint on the last system text block. If there are tools, they render before system — the marker on the last system block caches tools + system together. + +```json +"system": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}} +] +``` + +### Multi-turn conversations + +Put a breakpoint on the last content block of the most-recently-appended turn. Each subsequent request reuses the entire prior conversation prefix. Earlier breakpoints remain valid read points, so hits accrue incrementally as the conversation grows. + +```json +// Last content block of the last user turn +messages[-1].content[-1].cache_control = {"type": "ephemeral"} +``` + +### Shared prefix, varying suffix + +Many requests share a large fixed preamble (few-shot examples, retrieved docs, instructions) but differ in the final question. Put the breakpoint at the end of the **shared** portion, not at the end of the whole prompt — otherwise every request writes a distinct cache entry and nothing is ever read. + +```json +"messages": [{"role": "user", "content": [ + {"type": "text", "text": "", "cache_control": {"type": "ephemeral"}}, + {"type": "text", "text": ""} // no marker — differs every time +]}] +``` + +### Prompts that change from the beginning every time + +Don't cache. If the first 1K tokens differ per request, there is no reusable prefix. Adding `cache_control` only pays the cache-write premium with zero reads. Leave it off. + +--- + +## Architectural guidance + +These are the decisions that matter more than marker placement. Fix these first. + +**Keep the system prompt frozen.** Don't interpolate "current date: X", "mode: Y", "user name: Z" into the system prompt — those sit at the front of the prefix and invalidate everything downstream. Inject dynamic context as a user or assistant message later in `messages`. A message at turn 5 invalidates nothing before turn 5. + +**Don't change tools or model mid-conversation.** Tools render at position 0; adding, removing, or reordering a tool invalidates the entire cache. Same for switching models (caches are model-scoped). If you need "modes", don't swap the tool set — give Claude a tool that records the mode transition, or pass the mode as message content. Serialize tools deterministically (sort by name). + +**Fork operations must reuse the parent's exact prefix.** Side computations (summarization, compaction, sub-agents) often spin up a separate API call. If the fork rebuilds `system` / `tools` / `model` with any difference, it misses the parent's cache entirely. Copy the parent's `system`, `tools`, and `model` verbatim, then append fork-specific content at the end. + +--- + +## Silent invalidators + +When reviewing code, grep for these inside anything that feeds the prompt prefix: + +| Pattern | Why it breaks caching | +|---|---| +| `datetime.now()` / `Date.now()` / `time.time()` in system prompt | Prefix changes every request | +| `uuid4()` / `crypto.randomUUID()` / request IDs early in content | Same — every request is unique | +| `json.dumps(d)` without `sort_keys=True` / iterating a `set` | Non-deterministic serialization → prefix bytes differ | +| f-string interpolating session/user ID into system prompt | Per-user prefix; no cross-user sharing | +| Conditional system sections (`if flag: system += ...`) | Every flag combination is a distinct prefix | +| `tools=build_tools(user)` where set varies per user | Tools render at position 0; nothing caches across users | + +Fix by moving the dynamic piece after the last breakpoint, making it deterministic, or deleting it if it's not load-bearing. + +--- + +## API reference + +```json +"cache_control": {"type": "ephemeral"} // 5-minute TTL (default) +"cache_control": {"type": "ephemeral", "ttl": "1h"} // 1-hour TTL +``` + +- Max **4** `cache_control` breakpoints per request. +- Goes on any content block: system text blocks, tool definitions, message content blocks (`text`, `image`, `tool_use`, `tool_result`, `document`). +- Top-level `cache_control` on `messages.create()` auto-places on the last cacheable block — simplest option when you don't need fine-grained placement. +- Minimum cacheable prefix is model-dependent. Shorter prefixes silently won't cache even with a marker — no error, just `cache_creation_input_tokens: 0`: + +| Model | Minimum | +|---|---:| +| Opus 4.6, Opus 4.5, Haiku 4.5 | 4096 tokens | +| Sonnet 4.6, Haiku 3.5, Haiku 3 | 2048 tokens | +| Sonnet 4.5, Sonnet 4.1, Sonnet 4, Sonnet 3.7 | 1024 tokens | + +A 3K-token prompt caches on Sonnet 4.5 but silently won't on Opus 4.6. + +**Economics:** Cache reads cost ~0.1× base input price. Cache writes cost **1.25× for 5-minute TTL, 2× for 1-hour TTL**. Break-even depends on TTL: with 5-minute TTL, two requests break even (1.25× + 0.1× = 1.35× vs 2× uncached); with 1-hour TTL, you need at least three requests (2× + 0.2× = 2.2× vs 3× uncached). The 1-hour TTL keeps entries alive across gaps in bursty traffic, but the doubled write cost means it needs more reads to pay off. + +--- + +## Verifying cache hits + +The response `usage` object reports cache activity: + +| Field | Meaning | +|---|---| +| `cache_creation_input_tokens` | Tokens written to cache this request (you paid the ~1.25× write premium) | +| `cache_read_input_tokens` | Tokens served from cache this request (you paid ~0.1×) | +| `input_tokens` | Tokens processed at full price (not cached) | + +If `cache_read_input_tokens` is zero across repeated requests with identical prefixes, a silent invalidator is at work — diff the rendered prompt bytes between two requests to find it. + +**`input_tokens` is the uncached remainder only.** Total prompt size = `input_tokens + cache_creation_input_tokens + cache_read_input_tokens`. If your agent ran for hours but `input_tokens` shows 4K, the rest was served from cache — check the sum, not the single field. + +Language-specific access: `response.usage.cache_read_input_tokens` (Python/TS/Ruby), `$message->usage->cacheReadInputTokens` (PHP), `resp.Usage.CacheReadInputTokens` (Go/C#), `.usage().cacheReadInputTokens()` (Java). + +--- + +## Invalidation hierarchy + +Not every parameter change invalidates everything. The API has three cache tiers, and changes only invalidate their own tier and below: + +| Change | Tools cache | System cache | Messages cache | +|---|:---:|:---:|:---:| +| Tool definitions (add/remove/reorder) | ❌ | ❌ | ❌ | +| Model switch | ❌ | ❌ | ❌ | +| `speed`, web-search, citations toggle | ✅ | ❌ | ❌ | +| System prompt content | ✅ | ❌ | ❌ | +| `tool_choice`, images, `thinking` enable/disable | ✅ | ✅ | ❌ | +| Message content | ✅ | ✅ | ❌ | + +Implication: you can change `tool_choice` per-request or toggle `thinking` without losing the tools+system cache. Don't over-worry about these — only tool-definition and model changes force a full rebuild. + +--- + +## 20-block lookback window + +Each breakpoint walks backward **at most 20 content blocks** to find a prior cache entry. If a single turn adds more than 20 blocks (common in agentic loops with many tool_use/tool_result pairs), the next request's breakpoint won't find the previous cache and silently misses. + +Fix: place an intermediate breakpoint every ~15 blocks in long turns, or put the marker on a block that's within 20 of the previous turn's last cached block. + +--- + +## Concurrent-request timing + +A cache entry becomes readable only after the first response **begins streaming**. N parallel requests with identical prefixes all pay full price — none can read what the others are still writing. + +For fan-out patterns: send 1 request, await the first streamed token (not the full response), then fire the remaining N−1. They'll read the cache the first one just wrote. diff --git a/junie/versions/2285.4/skills/claude-api/shared/tool-use-concepts.md b/junie/versions/2285.4/skills/claude-api/shared/tool-use-concepts.md new file mode 100644 index 0000000..65d9637 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/shared/tool-use-concepts.md @@ -0,0 +1,327 @@ +# Tool Use Concepts + +This file covers the conceptual foundations of tool use with the Claude API. For language-specific code examples, see the `python/`, `typescript/`, or other language folders. For decision heuristics on which tools to expose, how to manage context in long-running agents, and caching strategy, see `agent-design.md`. + +## User-Defined Tools + +### Tool Definition Structure + +> **Note:** When using the Tool Runner (beta), tool schemas are generated automatically from your function signatures (Python), Zod schemas (TypeScript), annotated classes (Java), `jsonschema` struct tags (Go), or `BaseTool` subclasses (Ruby). The raw JSON schema format below is for the manual approach — including PHP's `BetaRunnableTool`, which wraps a run closure around a hand-written schema — or SDKs without tool runner support. + +Each tool requires a name, description, and JSON Schema for its inputs: + +```json +{ + "name": "get_weather", + "description": "Get current weather for a location", + "input_schema": { + "type": "object", + "properties": { + "location": { + "type": "string", + "description": "City and state, e.g., San Francisco, CA" + }, + "unit": { + "type": "string", + "enum": ["celsius", "fahrenheit"], + "description": "Temperature unit" + } + }, + "required": ["location"] + } +} +``` + +**Best practices for tool definitions:** + +- Use clear, descriptive names (e.g., `get_weather`, `search_database`, `send_email`) +- Write detailed descriptions — Claude uses these to decide when to use the tool +- Include descriptions for each property +- Use `enum` for parameters with a fixed set of values +- Mark truly required parameters in `required`; make others optional with defaults + +--- + +### Tool Choice Options + +Control when Claude uses tools: + +| Value | Behavior | +| --------------------------------- | --------------------------------------------- | +| `{"type": "auto"}` | Claude decides whether to use tools (default) | +| `{"type": "any"}` | Claude must use at least one tool | +| `{"type": "tool", "name": "..."}` | Claude must use the specified tool | +| `{"type": "none"}` | Claude cannot use tools | + +Any `tool_choice` value can also include `"disable_parallel_tool_use": true` to force Claude to use at most one tool per response. By default, Claude may request multiple tool calls in a single response. + +--- + +### Tool Runner vs Manual Loop + +**Tool Runner (Recommended):** The SDK's tool runner handles the agentic loop automatically — it calls the API, detects tool use requests, executes your tool functions, feeds results back to Claude, and repeats until Claude stops calling tools. Available in Python, TypeScript, Java, Go, Ruby, and PHP SDKs (beta). The Python SDK also provides MCP conversion helpers (`anthropic.lib.tools.mcp`) to convert MCP tools, prompts, and resources for use with the tool runner — see `python/claude-api/tool-use.md` for details. + +**Manual Agentic Loop:** Use when you need fine-grained control over the loop (e.g., custom logging, conditional tool execution, human-in-the-loop approval). Loop until `stop_reason == "end_turn"`, always append the full `response.content` to preserve tool_use blocks, and ensure each `tool_result` includes the matching `tool_use_id`. + +**Stop reasons for server-side tools:** When using server-side tools (code execution, web search, etc.), the API runs a server-side sampling loop. If this loop reaches its default limit of 10 iterations, the response will have `stop_reason: "pause_turn"`. To continue, re-send the user message and assistant response and make another API request — the server will resume where it left off. Do NOT add an extra user message like "Continue." — the API detects the trailing `server_tool_use` block and knows to resume automatically. + +```python +# Handle pause_turn in your agentic loop +if response.stop_reason == "pause_turn": + messages = [ + {"role": "user", "content": user_query}, + {"role": "assistant", "content": response.content}, + ] + # Make another API request — server resumes automatically + response = client.messages.create( + model="claude-opus-4-6", messages=messages, tools=tools + ) +``` + +Set a `max_continuations` limit (e.g., 5) to prevent infinite loops. For the full guide, see: `https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons` + +> **Security:** The tool runner executes your tool functions automatically whenever Claude requests them. For tools with side effects (sending emails, modifying databases, financial transactions), validate inputs within your tool functions and consider requiring confirmation for destructive operations. Use the manual agentic loop if you need human-in-the-loop approval before each tool execution. + +--- + +### Handling Tool Results + +When Claude uses a tool, the response contains a `tool_use` block. You must: + +1. Execute the tool with the provided input +2. Send the result back in a `tool_result` message +3. Continue the conversation + +**Error handling in tool results:** When a tool execution fails, set `"is_error": true` and provide an informative error message. Claude will typically acknowledge the error and either try a different approach or ask for clarification. + +**Multiple tool calls:** Claude can request multiple tools in a single response. Handle them all before continuing — send all results back in a single `user` message. + +--- + +## Server-Side Tools: Code Execution + +The code execution tool lets Claude run code in a secure, sandboxed container. Unlike user-defined tools, server-side tools run on Anthropic's infrastructure — you don't execute anything client-side. Just include the tool definition and Claude handles the rest. + +### Key Facts + +- Runs in an isolated container (1 CPU, 5 GiB RAM, 5 GiB disk) +- No internet access (fully sandboxed) +- Python 3.11 with data science libraries pre-installed +- Containers persist for 30 days and can be reused across requests +- Free when used with web search/web fetch tools; otherwise $0.05/hour after 1,550 free hours/month per organization + +### Tool Definition + +The tool requires no schema — just declare it in the `tools` array: + +```json +{ + "type": "code_execution_20260120", + "name": "code_execution" +} +``` + +Claude automatically gains access to `bash_code_execution` (run shell commands) and `text_editor_code_execution` (create/view/edit files). + +### Pre-installed Python Libraries + +- **Data science**: pandas, numpy, scipy, scikit-learn, statsmodels +- **Visualization**: matplotlib, seaborn +- **File processing**: openpyxl, xlsxwriter, pillow, pypdf, pdfplumber, python-docx, python-pptx +- **Math**: sympy, mpmath +- **Utilities**: tqdm, python-dateutil, pytz, sqlite3 + +Additional packages can be installed at runtime via `pip install`. + +### Supported File Types for Upload + +| Type | Extensions | +| ------ | ---------------------------------- | +| Data | CSV, Excel (.xlsx/.xls), JSON, XML | +| Images | JPEG, PNG, GIF, WebP | +| Text | .txt, .md, .py, .js, etc. | + +### Container Reuse + +Reuse containers across requests to maintain state (files, installed packages, variables). Extract the `container_id` from the first response and pass it to subsequent requests. + +### Response Structure + +The response contains interleaved text and tool result blocks: + +- `text` — Claude's explanation +- `server_tool_use` — What Claude is doing +- `bash_code_execution_tool_result` — Code execution output (check `return_code` for success/failure) +- `text_editor_code_execution_tool_result` — File operation results + +> **Security:** Always sanitize filenames with `os.path.basename()` / `path.basename()` before writing downloaded files to disk to prevent path traversal attacks. Write files to a dedicated output directory. + +--- + +## Server-Side Tools: Web Search and Web Fetch + +Web search and web fetch let Claude search the web and retrieve page content. They run server-side — just include the tool definitions and Claude handles queries, fetching, and result processing automatically. + +### Tool Definitions + +```json +[ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } +] +``` + +### Dynamic Filtering (Opus 4.6 / Sonnet 4.6) + +The `web_search_20260209` and `web_fetch_20260209` versions support **dynamic filtering** — Claude writes and executes code to filter search results before they reach the context window, improving accuracy and token efficiency. Dynamic filtering is built into these tool versions and activates automatically; you do not need to separately declare the `code_execution` tool or pass any beta header. + +```json +{ + "tools": [ + { "type": "web_search_20260209", "name": "web_search" }, + { "type": "web_fetch_20260209", "name": "web_fetch" } + ] +} +``` + +Without dynamic filtering, the previous `web_search_20250305` version is also available. + +> **Note:** Only include the standalone `code_execution` tool when your application needs code execution for its own purposes (data analysis, file processing, visualization) independent of web search. Including it alongside `_20260209` web tools creates a second execution environment that can confuse the model. + +--- + +## Server-Side Tools: Programmatic Tool Calling + +With standard tool use, each tool call is a round trip: Claude calls, the result enters Claude's context, Claude reasons, then calls the next tool. Chained calls accumulate latency and tokens — most of that intermediate data is never needed again. + +Programmatic tool calling lets Claude compose those calls into a script. The script runs in the code execution container; when it invokes a tool, the container pauses, the call executes, and the result returns to the running code (not to Claude's context). The script processes it with normal control flow. Only the final output returns to Claude. Use it when chaining many tool calls or when intermediate results are large and should be filtered before reaching the context window. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/programmatic-tool-calling` + +--- + +## Server-Side Tools: Tool Search + +The tool search tool lets Claude dynamically discover tools from large libraries without loading all definitions into the context window. Use it when you have many tools but only a few are relevant to any given request. Discovered tool schemas are appended to the request, not swapped in — this preserves the prompt cache (see `agent-design.md` §Caching for Agents). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/tool-search-tool` + +--- + +## Skills + +Skills package task-specific instructions that Claude loads only when relevant. Each skill is a folder containing a `SKILL.md` file. The skill's short description sits in context by default; Claude reads the full file when the current task calls for it. Use skills to keep specialized instructions out of the base system prompt without losing discoverability. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/skills` + +--- + +## Tool Use Examples + +You can provide sample tool calls directly in your tool definitions to demonstrate usage patterns and reduce parameter errors. This helps Claude understand how to correctly format tool inputs, especially for tools with complex schemas. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/implement-tool-use` + +--- + +## Server-Side Tools: Computer Use + +Computer use lets Claude interact with a desktop environment (screenshots, mouse, keyboard). It can be Anthropic-hosted (server-side, like code execution) or self-hosted (you provide the environment and execute actions client-side). + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/computer-use/overview` + +--- + +## Context Editing + +Context editing clears stale tool results and thinking blocks from the transcript as a long-running agent accumulates turns. Unlike compaction (which summarizes), context editing prunes — the cleared content is removed, not replaced. Use it when old tool outputs are no longer relevant and you want to keep the transcript lean without losing the conversation structure. Thresholds for what to clear are configurable. + +For full documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/build-with-claude/context-editing` + +--- + +## Client-Side Tools: Memory + +The memory tool enables Claude to store and retrieve information across conversations through a memory file directory. Claude can create, read, update, and delete files that persist between sessions. + +### Key Facts + +- Client-side tool — you control storage via your implementation +- Supports commands: `view`, `create`, `str_replace`, `insert`, `delete`, `rename` +- Operates on files in a `/memories` directory +- The Python, TypeScript, and Java SDKs provide helper classes/functions for implementing the memory backend + +> **Security:** Never store API keys, passwords, tokens, or other secrets in memory files. Be cautious with personally identifiable information (PII) — check data privacy regulations (GDPR, CCPA) before persisting user data. The reference implementations have no built-in access control; in multi-user systems, implement per-user memory directories and authentication in your tool handlers. + +For full implementation examples, use WebFetch: + +- Docs: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/memory-tool.md` + +--- + +## Structured Outputs + +Structured outputs constrain Claude's responses to follow a specific JSON schema, guaranteeing valid, parseable output. This is not a separate tool — it enhances the Messages API response format and/or tool parameter validation. + +Two features are available: + +- **JSON outputs** (`output_config.format`): Control Claude's response format +- **Strict tool use** (`strict: true`): Guarantee valid tool parameter schemas + +**Supported models:** Claude Opus 4.6, Claude Sonnet 4.6, and Claude Haiku 4.5. Legacy models (Claude Opus 4.5, Claude Opus 4.1) also support structured outputs. + +> **Recommended:** Use `client.messages.parse()` which automatically validates responses against your schema. When using `messages.create()` directly, use `output_config: {format: {...}}`. The `output_format` convenience parameter is also accepted by some SDK methods (e.g., `.parse()`), but `output_config.format` is the canonical API-level parameter. + +### JSON Schema Limitations + +**Supported:** + +- Basic types: object, array, string, integer, number, boolean, null +- `enum`, `const`, `anyOf`, `allOf`, `$ref`/`$def` +- String formats: `date-time`, `time`, `date`, `duration`, `email`, `hostname`, `uri`, `ipv4`, `ipv6`, `uuid` +- `additionalProperties: false` (required for all objects) + +**Not supported:** + +- Recursive schemas +- Numerical constraints (`minimum`, `maximum`, `multipleOf`) +- String constraints (`minLength`, `maxLength`) +- Complex array constraints +- `additionalProperties` set to anything other than `false` + +The Python and TypeScript SDKs automatically handle unsupported constraints by removing them from the schema sent to the API and validating them client-side. + +### Important Notes + +- **First request latency**: New schemas incur a one-time compilation cost. Subsequent requests with the same schema use a 24-hour cache. +- **Refusals**: If Claude refuses for safety reasons (`stop_reason: "refusal"`), the output may not match your schema. +- **Token limits**: If `stop_reason: "max_tokens"`, output may be incomplete. Increase `max_tokens`. +- **Incompatible with**: Citations (returns 400 error), message prefilling. +- **Works with**: Batches API, streaming, token counting, extended thinking. + +--- + +## Tips for Effective Tool Use + +1. **Provide detailed descriptions**: Claude relies heavily on descriptions to understand when and how to use tools +2. **Use specific tool names**: `get_current_weather` is better than `weather` +3. **Validate inputs**: Always validate tool inputs before execution +4. **Handle errors gracefully**: Return informative error messages so Claude can adapt +5. **Limit tool count**: Too many tools can confuse the model — keep the set focused +6. **Test tool interactions**: Verify Claude uses tools correctly in various scenarios + +For detailed tool use documentation, use WebFetch: + +- URL: `https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/claude-api/README.md b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/README.md new file mode 100644 index 0000000..3847621 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/README.md @@ -0,0 +1,333 @@ +# Claude API — TypeScript + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Basic Message Request + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [{ role: "user", content: "What is the capital of France?" }], +}); +// response.content is ContentBlock[] — a discriminated union. Narrow by .type +// before accessing .text (TypeScript will error on content[0].text without this). +for (const block of response.content) { + if (block.type === "text") { + console.log(block.text); + } +} +``` + +--- + +## System Prompts + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: + "You are a helpful coding assistant. Always provide examples in Python.", + messages: [{ role: "user", content: "How do I read a JSON file?" }], +}); +``` + +--- + +## Vision (Images) + +### URL + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "url", url: "https://example.com/image.png" }, + }, + { type: "text", text: "Describe this image" }, + ], + }, + ], +}); +``` + +### Base64 + +```typescript +import fs from "fs"; + +const imageData = fs.readFileSync("image.png").toString("base64"); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "image", + source: { type: "base64", media_type: "image/png", data: imageData }, + }, + { type: "text", text: "What's in this image?" }, + ], + }, + ], +}); +``` + +--- + +## Prompt Caching + +**Caching is a prefix match** — any byte change anywhere in the prefix invalidates everything after it. For placement patterns, architectural guidance (frozen system prompt, deterministic tool order, where to put volatile content), and the silent-invalidator audit checklist, read `shared/prompt-caching.md`. + +### Automatic Caching (Recommended) + +Use top-level `cache_control` to automatically cache the last cacheable block in the request: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, // auto-caches the last cacheable block + system: "You are an expert on this large document...", + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Manual Cache Control + +For fine-grained control, add `cache_control` to specific content blocks: + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral" }, // default TTL is 5 minutes + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// With explicit TTL (time-to-live) +const response2 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + system: [ + { + type: "text", + text: "You are an expert on this large document...", + cache_control: { type: "ephemeral", ttl: "1h" }, // 1 hour TTL + }, + ], + messages: [{ role: "user", content: "Summarize the key points" }], +}); +``` + +### Verifying Cache Hits + +```typescript +console.log(response.usage.cache_creation_input_tokens); // tokens written to cache (~1.25x cost) +console.log(response.usage.cache_read_input_tokens); // tokens served from cache (~0.1x cost) +console.log(response.usage.input_tokens); // uncached tokens (full cost) +``` + +If `cache_read_input_tokens` is zero across repeated identical-prefix requests, a silent invalidator is at work — `Date.now()` or a UUID in the system prompt, non-deterministic key ordering, or a varying tool set. See `shared/prompt-caching.md` for the full audit table. + +--- + +## Extended Thinking + +> **Opus 4.6 and Sonnet 4.6:** Use adaptive thinking. `budget_tokens` is deprecated on both Opus 4.6 and Sonnet 4.6. +> **Older models:** Use `thinking: {type: "enabled", budget_tokens: N}` (must be < `max_tokens`, min 1024). + +```typescript +// Opus 4.6: adaptive thinking (recommended) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + thinking: { type: "adaptive" }, + output_config: { effort: "high" }, // low | medium | high | max + messages: [ + { role: "user", content: "Solve this math problem step by step..." }, + ], +}); + +for (const block of response.content) { + if (block.type === "thinking") { + console.log("Thinking:", block.thinking); + } else if (block.type === "text") { + console.log("Response:", block.text); + } +} +``` + +--- + +## Error Handling + +Use the SDK's typed exception classes — never check error messages with string matching: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +try { + const response = await client.messages.create({...}); +} catch (error) { + if (error instanceof Anthropic.BadRequestError) { + console.error("Bad request:", error.message); + } else if (error instanceof Anthropic.AuthenticationError) { + console.error("Invalid API key"); + } else if (error instanceof Anthropic.RateLimitError) { + console.error("Rate limited - retry later"); + } else if (error instanceof Anthropic.APIError) { + console.error(`API error ${error.status}:`, error.message); + } +} +``` + +All classes extend `Anthropic.APIError` with a typed `status` field. Check from most specific to least specific. See [shared/error-codes.md](../../shared/error-codes.md) for the full error code reference. + +--- + +## Multi-Turn Conversations + +The API is stateless — send the full conversation history each time. Use `Anthropic.MessageParam[]` to type the messages array: + +```typescript +const messages: Anthropic.MessageParam[] = [ + { role: "user", content: "My name is Alice." }, + { role: "assistant", content: "Hello Alice! Nice to meet you." }, + { role: "user", content: "What's my name?" }, +]; + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: messages, +}); +``` + +**Rules:** + +- Consecutive same-role messages are allowed — the API combines them into a single turn +- First message must be `user` +- Use SDK types (`Anthropic.MessageParam`, `Anthropic.Message`, `Anthropic.Tool`, etc.) for all API data structures — don't redefine equivalent interfaces + +--- + +### Compaction (long conversations) + +> **Beta, Opus 4.6 and Sonnet 4.6.** When conversations approach the 200K context window, compaction automatically summarizes earlier context server-side. The API returns a `compaction` block; you must pass it back on subsequent requests — append `response.content`, not just the text. + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const messages: Anthropic.Beta.BetaMessageParam[] = []; + +async function chat(userMessage: string): Promise { + messages.push({ role: "user", content: userMessage }); + + const response = await client.beta.messages.create({ + betas: ["compact-2026-01-12"], + model: "claude-opus-4-6", + max_tokens: 16000, + messages, + context_management: { + edits: [{ type: "compact_20260112" }], + }, + }); + + // Append full content — compaction blocks must be preserved + messages.push({ role: "assistant", content: response.content }); + + const textBlock = response.content.find( + (b): b is Anthropic.Beta.BetaTextBlock => b.type === "text", + ); + return textBlock?.text ?? ""; +} + +// Compaction triggers automatically when context grows large +console.log(await chat("Help me build a Python web scraper")); +console.log(await chat("Add support for JavaScript-rendered pages")); +console.log(await chat("Now add rate limiting and error handling")); +``` + +--- + +## Stop Reasons + +The `stop_reason` field in the response indicates why the model stopped generating: + +| Value | Meaning | +| --------------- | --------------------------------------------------------------- | +| `end_turn` | Claude finished its response naturally | +| `max_tokens` | Hit the `max_tokens` limit — increase it or use streaming | +| `stop_sequence` | Hit a custom stop sequence | +| `tool_use` | Claude wants to call a tool — execute it and continue | +| `pause_turn` | Model paused and can be resumed (agentic flows) | +| `refusal` | Claude refused for safety reasons — output may not match schema | + +--- + +## Cost Optimization Strategies + +### 1. Use Prompt Caching for Repeated Context + +```typescript +// Automatic caching (simplest — caches the last cacheable block) +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + cache_control: { type: "ephemeral" }, + system: largeDocumentText, // e.g., 50KB of context + messages: [{ role: "user", content: "Summarize the key points" }], +}); + +// First request: full cost +// Subsequent requests: ~90% cheaper for cached portion +``` + +### 2. Use Token Counting Before Requests + +```typescript +const countResponse = await client.messages.countTokens({ + model: "claude-opus-4-6", + messages: messages, + system: system, +}); + +const estimatedInputCost = countResponse.input_tokens * 0.000005; // $5/1M tokens +console.log(`Estimated input cost: $${estimatedInputCost.toFixed(4)}`); +``` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/claude-api/batches.md b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/batches.md new file mode 100644 index 0000000..e7a9fa3 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/batches.md @@ -0,0 +1,106 @@ +# Message Batches API — TypeScript + +The Batches API (`POST /v1/messages/batches`) processes Messages API requests asynchronously at 50% of standard prices. + +## Key Facts + +- Up to 100,000 requests or 256 MB per batch +- Most batches complete within 1 hour; maximum 24 hours +- Results available for 29 days after creation +- 50% cost reduction on all token usage +- All Messages API features supported (vision, tools, caching, etc.) + +--- + +## Create a Batch + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const messageBatch = await client.messages.batches.create({ + requests: [ + { + custom_id: "request-1", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Summarize climate change impacts" }, + ], + }, + }, + { + custom_id: "request-2", + params: { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { role: "user", content: "Explain quantum computing basics" }, + ], + }, + }, + ], +}); + +console.log(`Batch ID: ${messageBatch.id}`); +console.log(`Status: ${messageBatch.processing_status}`); +``` + +--- + +## Poll for Completion + +```typescript +let batch; +while (true) { + batch = await client.messages.batches.retrieve(messageBatch.id); + if (batch.processing_status === "ended") break; + console.log( + `Status: ${batch.processing_status}, processing: ${batch.request_counts.processing}`, + ); + await new Promise((resolve) => setTimeout(resolve, 60_000)); +} + +console.log("Batch complete!"); +console.log(`Succeeded: ${batch.request_counts.succeeded}`); +console.log(`Errored: ${batch.request_counts.errored}`); +``` + +--- + +## Retrieve Results + +```typescript +for await (const result of await client.messages.batches.results( + messageBatch.id, +)) { + switch (result.result.type) { + case "succeeded": + console.log( + `[${result.custom_id}] ${result.result.message.content[0].text.slice(0, 100)}`, + ); + break; + case "errored": + if (result.result.error.type === "invalid_request") { + console.log(`[${result.custom_id}] Validation error - fix and retry`); + } else { + console.log(`[${result.custom_id}] Server error - safe to retry`); + } + break; + case "expired": + console.log(`[${result.custom_id}] Expired - resubmit`); + break; + } +} +``` + +--- + +## Cancel a Batch + +```typescript +const cancelled = await client.messages.batches.cancel(messageBatch.id); +console.log(`Status: ${cancelled.processing_status}`); // "canceling" +``` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/claude-api/files-api.md b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/files-api.md new file mode 100644 index 0000000..5f1223d --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/files-api.md @@ -0,0 +1,98 @@ +# Files API — TypeScript + +The Files API uploads files for use in Messages API requests. Reference files via `file_id` in content blocks, avoiding re-uploads across multiple API calls. + +**Beta:** Pass `betas: ["files-api-2025-04-14"]` in your API calls (the SDK sets the required header automatically). + +## Key Facts + +- Maximum file size: 500 MB +- Total storage: 100 GB per organization +- Files persist until deleted +- File operations (upload, list, delete) are free; content used in messages is billed as input tokens +- Not available on Amazon Bedrock or Google Vertex AI + +--- + +## Upload a File + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import fs from "fs"; + +const client = new Anthropic(); + +const uploaded = await client.beta.files.upload({ + file: await toFile(fs.createReadStream("report.pdf"), undefined, { + type: "application/pdf", + }), + betas: ["files-api-2025-04-14"], +}); + +console.log(`File ID: ${uploaded.id}`); +console.log(`Size: ${uploaded.size_bytes} bytes`); +``` + +--- + +## Use a File in Messages + +### PDF / Text Document + +```typescript +const response = await client.beta.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { type: "text", text: "Summarize the key findings in this report." }, + { + type: "document", + source: { type: "file", file_id: uploaded.id }, + title: "Q4 Report", + citations: { enabled: true }, + }, + ], + }, + ], + betas: ["files-api-2025-04-14"], +}); + +console.log(response.content[0].text); +``` + +--- + +## Manage Files + +### List Files + +```typescript +const files = await client.beta.files.list({ + betas: ["files-api-2025-04-14"], +}); +for (const f of files.data) { + console.log(`${f.id}: ${f.filename} (${f.size_bytes} bytes)`); +} +``` + +### Delete a File + +```typescript +await client.beta.files.delete("file_011CNha8iCJcU1wXNR6q4V8w", { + betas: ["files-api-2025-04-14"], +}); +``` + +### Download a File + +```typescript +const response = await client.beta.files.download( + "file_011CNha8iCJcU1wXNR6q4V8w", + { betas: ["files-api-2025-04-14"] }, +); +const content = Buffer.from(await response.arrayBuffer()); +await fs.promises.writeFile("output.txt", content); +``` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/claude-api/streaming.md b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/streaming.md new file mode 100644 index 0000000..f6a450f --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/streaming.md @@ -0,0 +1,178 @@ +# Streaming — TypeScript + +## Quick Start + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Write a story" }], +}); + +for await (const event of stream) { + if ( + event.type === "content_block_delta" && + event.delta.type === "text_delta" + ) { + process.stdout.write(event.delta.text); + } +} +``` + +--- + +## Handling Different Content Types + +> **Opus 4.6:** Use `thinking: {type: "adaptive"}`. On older models, use `thinking: {type: "enabled", budget_tokens: N}` instead. + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + thinking: { type: "adaptive" }, + messages: [{ role: "user", content: "Analyze this problem" }], +}); + +for await (const event of stream) { + switch (event.type) { + case "content_block_start": + switch (event.content_block.type) { + case "thinking": + console.log("\n[Thinking...]"); + break; + case "text": + console.log("\n[Response:]"); + break; + } + break; + case "content_block_delta": + switch (event.delta.type) { + case "thinking_delta": + process.stdout.write(event.delta.thinking); + break; + case "text_delta": + process.stdout.write(event.delta.text); + break; + } + break; + } +} +``` + +--- + +## Streaming with Tool Use (Tool Runner) + +Use the tool runner with `stream: true`. The outer loop iterates over tool runner iterations (messages), the inner loop processes stream events: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + }), + run: async ({ location }) => `72°F and sunny in ${location}`, +}); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools: [getWeather], + messages: [ + { role: "user", content: "What's the weather in Paris and London?" }, + ], + stream: true, +}); + +// Outer loop: each tool runner iteration +for await (const messageStream of runner) { + // Inner loop: stream events for this iteration + for await (const event of messageStream) { + switch (event.type) { + case "content_block_delta": + switch (event.delta.type) { + case "text_delta": + process.stdout.write(event.delta.text); + break; + case "input_json_delta": + // Tool input being streamed + break; + } + break; + } + } +} +``` + +--- + +## Getting the Final Message + +```typescript +const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + messages: [{ role: "user", content: "Hello" }], +}); + +for await (const event of stream) { + // Process events... +} + +const finalMessage = await stream.finalMessage(); +console.log(`Tokens used: ${finalMessage.usage.output_tokens}`); +``` + +--- + +## Stream Event Types + +| Event Type | Description | When it fires | +| --------------------- | --------------------------- | --------------------------------- | +| `message_start` | Contains message metadata | Once at the beginning | +| `content_block_start` | New content block beginning | When a text/tool_use block starts | +| `content_block_delta` | Incremental content update | For each token/chunk | +| `content_block_stop` | Content block complete | When a block finishes | +| `message_delta` | Message-level updates | Contains `stop_reason`, usage | +| `message_stop` | Message complete | Once at the end | + +## Best Practices + +1. **Always flush output** — Use `process.stdout.write()` for immediate display +2. **Handle partial responses** — If the stream is interrupted, you may have incomplete content +3. **Track token usage** — The `message_delta` event contains usage information +4. **Use `finalMessage()`** — Get the complete `Anthropic.Message` object even when streaming. Don't wrap `.on()` events in `new Promise()` — `finalMessage()` handles all completion/error/abort states internally +5. **Buffer for web UIs** — Consider buffering a few tokens before rendering to avoid excessive DOM updates +6. **Use `stream.on("text", ...)` for deltas** — The `text` event provides just the delta string, simpler than manually filtering `content_block_delta` events +7. **For agentic loops with streaming** — See the [Streaming Manual Loop](./tool-use.md#streaming-manual-loop) section in tool-use.md for combining `stream()` + `finalMessage()` with a tool-use loop + +## Raw SSE Format + +If using raw HTTP (not SDKs), the stream returns Server-Sent Events: + +``` +event: message_start +data: {"type":"message_start","message":{"id":"msg_...","type":"message",...}} + +event: content_block_start +data: {"type":"content_block_start","index":0,"content_block":{"type":"text","text":""}} + +event: content_block_delta +data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"Hello"}} + +event: content_block_stop +data: {"type":"content_block_stop","index":0} + +event: message_delta +data: {"type":"message_delta","delta":{"stop_reason":"end_turn"},"usage":{"output_tokens":12}} + +event: message_stop +data: {"type":"message_stop"} +``` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/claude-api/tool-use.md b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/tool-use.md new file mode 100644 index 0000000..28525c6 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/claude-api/tool-use.md @@ -0,0 +1,527 @@ +# Tool Use — TypeScript + +For conceptual overview (tool definitions, tool choice, tips), see [shared/tool-use-concepts.md](../../shared/tool-use-concepts.md). + +## Tool Runner (Recommended) + +**Beta:** The tool runner is in beta in the TypeScript SDK. + +Use `betaZodTool` with Zod schemas to define tools with a `run` function, then pass them to `client.beta.messages.toolRunner()`: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { betaZodTool } from "@anthropic-ai/sdk/helpers/beta/zod"; +import { z } from "zod"; + +const client = new Anthropic(); + +const getWeather = betaZodTool({ + name: "get_weather", + description: "Get current weather for a location", + inputSchema: z.object({ + location: z.string().describe("City and state, e.g., San Francisco, CA"), + unit: z.enum(["celsius", "fahrenheit"]).optional(), + }), + run: async (input) => { + // Your implementation here + return `72°F and sunny in ${input.location}`; + }, +}); + +// The tool runner handles the agentic loop and returns the final message +const finalMessage = await client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [getWeather], + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +console.log(finalMessage.content); +``` + +**Key benefits of the tool runner:** + +- No manual loop — the SDK handles calling tools and feeding results back +- Type-safe tool inputs via Zod schemas +- Tool schemas are generated automatically from Zod definitions +- Iteration stops automatically when Claude has no more tool calls + +--- + +## Manual Agentic Loop + +Use this when you need fine-grained control (custom logging, conditional tool execution, streaming individual iterations, human-in-the-loop approval): + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; // Your tool definitions +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: messages, + }); + + if (response.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (response.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: response.content }); + continue; + } + + const toolUseBlocks = response.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: response.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +### Streaming Manual Loop + +Use `client.messages.stream()` + `finalMessage()` instead of `.create()` when you need streaming within a manual loop. Text deltas are streamed on each iteration; `finalMessage()` collects the complete `Message` so you can inspect `stop_reason` and extract tool-use blocks: + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); +const tools: Anthropic.Tool[] = [...]; +let messages: Anthropic.MessageParam[] = [{ role: "user", content: userInput }]; + +while (true) { + const stream = client.messages.stream({ + model: "claude-opus-4-6", + max_tokens: 64000, + tools, + messages, + }); + + // Stream text deltas on each iteration + stream.on("text", (delta) => { + process.stdout.write(delta); + }); + + // finalMessage() resolves with the complete Message — no need to + // manually wire up .on("message") / .on("error") / .on("abort") + const message = await stream.finalMessage(); + + if (message.stop_reason === "end_turn") break; + + // Server-side tool hit iteration limit; append assistant turn and re-send to continue + if (message.stop_reason === "pause_turn") { + messages.push({ role: "assistant", content: message.content }); + continue; + } + + const toolUseBlocks = message.content.filter( + (b): b is Anthropic.ToolUseBlock => b.type === "tool_use", + ); + + messages.push({ role: "assistant", content: message.content }); + + const toolResults: Anthropic.ToolResultBlockParam[] = []; + for (const tool of toolUseBlocks) { + const result = await executeTool(tool.name, tool.input); + toolResults.push({ + type: "tool_result", + tool_use_id: tool.id, + content: result, + }); + } + + messages.push({ role: "user", content: toolResults }); +} +``` + +> **Important:** Don't wrap `.on()` events in `new Promise()` to collect the final message — use `stream.finalMessage()` instead. The SDK handles all error/abort/completion states internally. + +> **Error handling in the loop:** Use the SDK's typed exceptions (e.g., `Anthropic.RateLimitError`, `Anthropic.APIError`) — see [Error Handling](./README.md#error-handling) for examples. Don't check error messages with string matching. + +> **SDK types:** Use `Anthropic.MessageParam`, `Anthropic.Tool`, `Anthropic.ToolUseBlock`, `Anthropic.ToolResultBlockParam`, `Anthropic.Message`, etc. for all API-related data structures. Don't redefine equivalent interfaces. + +--- + +## Handling Tool Results + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); + +for (const block of response.content) { + if (block.type === "tool_use") { + const result = await executeTool(block.name, block.input); + + const followup = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + messages: [ + { role: "user", content: "What's the weather in Paris?" }, + { role: "assistant", content: response.content }, + { + role: "user", + content: [ + { type: "tool_result", tool_use_id: block.id, content: result }, + ], + }, + ], + }); + } +} +``` + +--- + +## Tool Choice + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: tools, + tool_choice: { type: "tool", name: "get_weather" }, + messages: [{ role: "user", content: "What's the weather in Paris?" }], +}); +``` + +--- + +## Server-Side Tools + +Version-suffixed `type` literals; `name` is fixed per interface. Pass plain object literals — the `ToolUnion` type is satisfied structurally. **The `name`/`type` pair must match the interface**: mixing `str_replace_based_edit_tool` (20250728 name) with `text_editor_20250124` (which expects `str_replace_editor`) is a TS2322. + +**Don't type-annotate as `Tool[]`** — `Tool` is just the custom-tool variant. Let structural typing infer from the `tools` param, or annotate as `Anthropic.Messages.ToolUnion[]` if you must: + +```typescript +// ✓ let inference work — no annotation +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [ + { type: "text_editor_20250728", name: "str_replace_based_edit_tool" }, + { type: "bash_20250124", name: "bash" }, + { type: "web_search_20260209", name: "web_search" }, + { type: "code_execution_20260120", name: "code_execution" }, + ], + messages: [{ role: "user", content: "..." }], +}); + +// ✗ this is a TS2352 — Tool is the CUSTOM tool variant only +// const tools: Anthropic.Tool[] = [{ type: "text_editor_20250728", ... }] +``` + +| Interface | `name` | `type` | +|---|---|---| +| `ToolTextEditor20250124` | `str_replace_editor` | `text_editor_20250124` | +| `ToolTextEditor20250429` | `str_replace_based_edit_tool` | `text_editor_20250429` | +| `ToolTextEditor20250728` | `str_replace_based_edit_tool` | `text_editor_20250728` | +| `ToolBash20250124` | `bash` | `bash_20250124` | +| `WebSearchTool20260209` | `web_search` | `web_search_20260209` | +| `WebFetchTool20260209` | `web_fetch` | `web_fetch_20260209` | +| `CodeExecutionTool20260120` | `code_execution` | `code_execution_20260120` | + +**Don't mix beta and non-beta types**: if you call `client.beta.messages.create()`, the response `content` is `BetaContentBlock[]` — you cannot pass that to a non-beta `ContentBlockParam[]` without narrowing each element. + +--- + + +## Code Execution + +### Basic Usage + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +const client = new Anthropic(); + +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Calculate the mean and standard deviation of [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +### Reading Local Files (ESM note) + +`__dirname` doesn't exist in ES modules. For script-relative paths use `import.meta.url`: + +```typescript +import { readFileSync } from "fs"; +import { fileURLToPath } from "url"; +import { dirname, join } from "path"; + +const __dirname = dirname(fileURLToPath(import.meta.url)); +const pdfBytes = readFileSync(join(__dirname, "sample.pdf")); +``` + +Or use a CWD-relative path if the script runs from a known directory: `readFileSync("./sample.pdf")`. + +### Upload Files for Analysis + +```typescript +import Anthropic, { toFile } from "@anthropic-ai/sdk"; +import { createReadStream } from "fs"; + +const client = new Anthropic(); + +// 1. Upload a file +const uploaded = await client.beta.files.upload({ + file: await toFile(createReadStream("sales_data.csv"), undefined, { + type: "text/csv", + }), + betas: ["files-api-2025-04-14"], +}); + +// 2. Pass to code execution +// Code execution is GA; Files API is still beta (pass via RequestOptions) +const response = await client.messages.create( + { + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: [ + { + type: "text", + text: "Analyze this sales data. Show trends and create a visualization.", + }, + { type: "container_upload", file_id: uploaded.id }, + ], + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], + }, + { headers: { "anthropic-beta": "files-api-2025-04-14" } }, +); +``` + +### Retrieve Generated Files + +```typescript +import path from "path"; +import fs from "fs"; + +const OUTPUT_DIR = "./claude_outputs"; +await fs.promises.mkdir(OUTPUT_DIR, { recursive: true }); + +for (const block of response.content) { + if (block.type === "bash_code_execution_tool_result") { + const result = block.content; + if (result.type === "bash_code_execution_result" && result.content) { + for (const fileRef of result.content) { + if (fileRef.type === "bash_code_execution_output") { + const metadata = await client.beta.files.retrieveMetadata( + fileRef.file_id, + ); + const downloadResponse = await client.beta.files.download(fileRef.file_id); + const fileBytes = Buffer.from(await downloadResponse.arrayBuffer()); + const safeName = path.basename(metadata.filename); + if (!safeName || safeName === "." || safeName === "..") { + console.warn(`Skipping invalid filename: ${metadata.filename}`); + continue; + } + const outputPath = path.join(OUTPUT_DIR, safeName); + await fs.promises.writeFile(outputPath, fileBytes); + console.log(`Saved: ${outputPath}`); + } + } + } + } +} +``` + +### Container Reuse + +```typescript +// First request: set up environment +const response1 = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Install tabulate and create data.json with sample user data", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); + +// Reuse container +// container is nullable — set only when using server-side code execution +const containerId = response1.container!.id; + +const response2 = await client.messages.create({ + container: containerId, + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Read data.json and display as a formatted table", + }, + ], + tools: [{ type: "code_execution_20260120", name: "code_execution" }], +}); +``` + +--- + +## Memory Tool + +### Basic Usage + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Remember that my preferred language is TypeScript.", + }, + ], + tools: [{ type: "memory_20250818", name: "memory" }], +}); +``` + +### SDK Memory Helper + +Use `betaMemoryTool` with a `MemoryToolHandlers` implementation: + +```typescript +import { + betaMemoryTool, + type MemoryToolHandlers, +} from "@anthropic-ai/sdk/helpers/beta/memory"; + +const handlers: MemoryToolHandlers = { + async view(command) { ... }, + async create(command) { ... }, + async str_replace(command) { ... }, + async insert(command) { ... }, + async delete(command) { ... }, + async rename(command) { ... }, +}; + +const memory = betaMemoryTool(handlers); + +const runner = client.beta.messages.toolRunner({ + model: "claude-opus-4-6", + max_tokens: 16000, + tools: [memory], + messages: [{ role: "user", content: "Remember my preferences" }], +}); + +for await (const message of runner) { + console.log(message); +} +``` + +For full implementation examples, use WebFetch: + +- `https://github.com/anthropics/anthropic-sdk-typescript/blob/main/examples/tools-helpers-memory.ts` + +--- + +## Structured Outputs + +### JSON Outputs (Zod — Recommended) + +```typescript +import Anthropic from "@anthropic-ai/sdk"; +import { z } from "zod"; +import { zodOutputFormat } from "@anthropic-ai/sdk/helpers/zod"; + +const ContactInfoSchema = z.object({ + name: z.string(), + email: z.string(), + plan: z.string(), + interests: z.array(z.string()), + demo_requested: z.boolean(), +}); + +const client = new Anthropic(); + +const response = await client.messages.parse({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: + "Extract: Jane Doe (jane@co.com) wants Enterprise, interested in API and SDKs, wants a demo.", + }, + ], + output_config: { + format: zodOutputFormat(ContactInfoSchema), + }, +}); + +// parsed_output is null if parsing failed — assert or guard +console.log(response.parsed_output!.name); // "Jane Doe" +``` + +### Strict Tool Use + +```typescript +const response = await client.messages.create({ + model: "claude-opus-4-6", + max_tokens: 16000, + messages: [ + { + role: "user", + content: "Book a flight to Tokyo for 2 passengers on March 15", + }, + ], + tools: [ + { + name: "book_flight", + description: "Book a flight to a destination", + strict: true, + input_schema: { + type: "object", + properties: { + destination: { type: "string" }, + date: { type: "string", format: "date" }, + passengers: { + type: "integer", + enum: [1, 2, 3, 4, 5, 6, 7, 8], + }, + }, + required: ["destination", "date", "passengers"], + additionalProperties: false, + }, + }, + ], +}); +``` diff --git a/junie/versions/2285.4/skills/claude-api/typescript/managed-agents/README.md b/junie/versions/2285.4/skills/claude-api/typescript/managed-agents/README.md new file mode 100644 index 0000000..b4f2a54 --- /dev/null +++ b/junie/versions/2285.4/skills/claude-api/typescript/managed-agents/README.md @@ -0,0 +1,359 @@ +# Managed Agents — TypeScript + +> **Bindings not shown here:** This README covers the most common managed-agents flows for TypeScript. If you need a class, method, namespace, field, or behavior that isn't shown, WebFetch the TypeScript SDK repo **or the relevant docs page** from `shared/live-sources.md` rather than guess. Do not extrapolate from cURL shapes or another language's SDK. + +> **Agents are persistent — create once, reference by ID.** Store the agent ID returned by `agents.create` and pass it to every subsequent `sessions.create`; do not call `agents.create` in the request path. The Anthropic CLI is one convenient way to create agents and environments from version-controlled YAML — its URL is in `shared/live-sources.md`. The examples below show in-code creation for completeness; in production the create call belongs in setup, not in the request path. + +## Installation + +```bash +npm install @anthropic-ai/sdk +``` + +## Client Initialization + +```typescript +import Anthropic from "@anthropic-ai/sdk"; + +// Default (uses ANTHROPIC_API_KEY env var) +const client = new Anthropic(); + +// Explicit API key +const client = new Anthropic({ apiKey: "your-api-key" }); +``` + +--- + +## Create an Environment + +```typescript +const environment = await client.beta.environments.create( + { + name: "my-dev-env", + config: { + type: "cloud", + networking: { type: "unrestricted" }, + }, + }, +); +console.log(environment.id); // env_... +``` + +--- + +## Create an Agent (required first step) + +> ⚠️ **There is no inline agent config.** `model`/`system`/`tools` live on the agent object, not the session. Always start with `agents.create()` — the session only takes `agent: { type: "agent", id: agent.id }`. + +### Minimal + +```typescript +// 1. Create the agent (reusable, versioned) +const agent = await client.beta.agents.create( + { + name: "Coding Assistant", + model: "claude-opus-4-6", + tools: [{ type: "agent_toolset_20260401", default_config: { enabled: true } }], + }, +); + +// 2. Start a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + }, +); +console.log(session.id, session.status); +``` + +### With system prompt and custom tools + +```typescript +const agent = await client.beta.agents.create( + { + name: "Code Reviewer", + model: "claude-opus-4-6", + system: "You are a senior code reviewer.", + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { + type: "custom", + name: "run_tests", + description: "Run the test suite", + input_schema: { + type: "object", + properties: { + test_path: { type: "string", description: "Path to test file" }, + }, + required: ["test_path"], + }, + }, + ], + }, +); + +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + title: "Code review session", + resources: [ + { + type: "github_repository", + url: "https://github.com/owner/repo", + mount_path: "/workspace/repo", + authorization_token: process.env.GITHUB_TOKEN, + branch: "main", + }, + ], + }, +); +``` + +--- + +## Send a User Message + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.message", + content: [{ type: "text", text: "Review the auth module" }], + }, + ], + }, +); +``` + +> 💡 **Stream-first:** Open the stream *before* (or concurrently with) sending the message. The stream only delivers events that occur after it opens — stream-after-send means early events arrive buffered in one batch. See [Steering Patterns](../../shared/managed-agents-events.md#steering-patterns). + +--- + +## Stream Events (SSE) + +```typescript +// Stream-first: open stream and send concurrently +const [events] = await Promise.all([ + collectStream(session.id), + client.beta.sessions.events.send( + session.id, + { events: [{ type: "user.message", content: [{ type: "text", text: "..." }] }] }, + ), +]); + +// Standalone stream iteration: +const stream = await client.beta.sessions.stream( + session.id, +); + +for await (const event of stream) { + switch (event.type) { + case "agent.message": + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + break; + case "agent.custom_tool_use": + // Custom tool invocation — session is now idle + console.log(`\nCustom tool call: ${event.tool_name}`); + console.log(`Input: ${JSON.stringify(event.input)}`); + break; + case "session.status_idle": + console.log("\n--- Agent idle ---"); + break; + case "session.status_terminated": + console.log("\n--- Session terminated ---"); + break; + } +} +``` + +--- + +## Provide Custom Tool Result + +```typescript +await client.beta.sessions.events.send( + session.id, + { + events: [ + { + type: "user.custom_tool_result", + custom_tool_use_id: "sevt_abc123", + content: [{ type: "text", text: "All 42 tests passed." }], + }, + ], + }, +); +``` + +--- + +## Poll Events + +```typescript +const events = await client.beta.sessions.events.list( + session.id, +); +for (const event of events.data) { + console.log(`${event.type}: ${event.id}`); +} +``` + +--- + +## Full Streaming Loop with Custom Tools + +```typescript +function runCustomTool(toolName: string, toolInput: unknown): string { + if (toolName === "run_tests") { + // Your tool implementation here + return "All tests passed."; + } + return `Unknown tool: ${toolName}`; +} + +async function runSession(client: Anthropic, sessionId: string) { + while (true) { + const stream = await client.beta.sessions.stream( + sessionId, + ); + + const toolCalls: Array<{ custom_tool_use_id: string; tool_name: string; input: unknown }> = []; + + for await (const event of stream) { + if (event.type === "agent.message") { + for (const block of event.content) { + if (block.type === "text") { + process.stdout.write(block.text); + } + } + } else if (event.type === "agent.custom_tool_use") { + toolCalls.push({ + id: event.id, + tool_name: event.tool_name, + input: event.input, + }); + } else if (event.type === "session.status_idle") { + break; + } else if (event.type === "session.status_terminated") { + return; + } + } + + if (toolCalls.length === 0) break; + + // Process custom tool calls + const results = toolCalls.map((call) => ({ + type: "user.custom_tool_result" as const, + custom_tool_use_id: call.id, + content: [{ type: "text" as const, text: runCustomTool(call.tool_name, call.input) }], + })); + + await client.beta.sessions.events.send( + sessionId, + { events: results }, + ); + } +} +``` + +--- + +## Upload a File + +```typescript +import fs from "fs"; + +const file = await client.beta.files.upload({ + file: fs.createReadStream("data.csv"), + purpose: "agent", +}); + +// Use in a session +const session = await client.beta.sessions.create( + { + agent: { type: "agent", id: agent.id, version: agent.version }, + environment_id: environment.id, + resources: [{ type: "file", file_id: file.id, mount_path: "/workspace/data.csv" }], + }, +); +``` + +--- + +## List and Download Session Files + +List files the agent wrote to `/mnt/session/outputs/` during a session, then download them. + +```typescript +import fs from "fs"; + +// List files associated with a session +const files = await client.beta.files.list({ + scope: session.id, +}); +for (const f of files.data) { + console.log(f.filename, f.size_bytes); + + // Download and save to disk + const resp = await client.beta.files.download(f.id); + const buffer = Buffer.from(await resp.arrayBuffer()); + fs.writeFileSync(f.filename, buffer); +} +``` + +> 💡 There's a brief indexing lag (~1–3s) between `session.status_idle` and output files appearing in `files.list`. Retry once or twice if the list is empty. + +--- + +## Session Management + +```typescript +// Get session details +const session = await client.beta.sessions.retrieve("sess_abc123"); +console.log(session.status, session.usage); + +// List sessions +const sessions = await client.beta.sessions.list(); + +// Delete a session +await client.beta.sessions.delete("sess_abc123"); + +// Archive a session +await client.beta.sessions.archive("sess_abc123"); +``` + +--- + +## MCP Server Integration + +```typescript +// Agent declares MCP server (no auth here — auth goes in a vault) +const agent = await client.beta.agents.create({ + name: "MCP Agent", + model: "claude-opus-4-6", + mcp_servers: [ + { type: "url", name: "my-tools", url: "https://my-mcp-server.example.com/sse" }, + ], + tools: [ + { type: "agent_toolset_20260401", default_config: { enabled: true } }, + { type: "mcp_toolset", mcp_server_name: "my-tools" }, + ], +}); + +// Session attaches vault(s) containing credentials for those MCP server URLs +const session = await client.beta.sessions.create({ + agent: agent.id, + environment_id: environment.id, + vault_ids: [vault.id], +}); +``` + +See `shared/managed-agents-tools.md` §Vaults for creating vaults and adding credentials. diff --git a/junie/versions/2285.4/skills/demo-setup/SKILL.md b/junie/versions/2285.4/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2285.4/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2285.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2285.4/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2285.4/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/BYOK.md b/junie/versions/2285.4/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..7008ef3 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,186 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..fda784a --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,144 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2285.4/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2285.4/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..8cf3e64 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..d3dfb08 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,108 @@ +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..df04555 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,138 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..fde2f59 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,455 @@ +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..1498840 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..973dfe9 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,339 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2285.4/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2285.4/skills/junie-cli-docs/SKILL.md b/junie/versions/2285.4/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..d332741 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4045 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+T` shortcut. +When in the Transcript view, use `Ctrl+N` to load older entries, or `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": ["copilot"], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +> Currently, only the `Ingrazzio` kind is functional. Selecting any other kind will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` proxy kind is currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload. Always shown in the TUI as `Stop hook context: …`. It is also delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. Shown in the TUI as `Stop hook: …`. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message. For sync hooks, currently honoured by the `Stop` executor only. For async hooks, published on completion as ` hook: ` for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+T`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Parallel sessions and worktrees + +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2285.4/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2285.4/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..11f7240 --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,80 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open the full transcript of the current session. | +| `Ctrl+N` | Navigate the transcript of the current session after opening it (`Ctrl+T`). | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + + diff --git a/junie/versions/2285.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2285.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..7a888ac --- /dev/null +++ b/junie/versions/2285.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,157 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed tail + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2548.5/skills/demo-setup/SKILL.md b/junie/versions/2548.5/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2548.5/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2548.5/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2548.5/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2548.5/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/BYOK.md b/junie/versions/2548.5/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..37b28ac --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,242 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..ebd1a63 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,197 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2548.5/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2548.5/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..a271ac9 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..a68fa1d --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,113 @@ +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..43827f0 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,162 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..fde2f59 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,455 @@ +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..d241854 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..16fed04 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,344 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2548.5/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2548.5/skills/junie-cli-docs/SKILL.md b/junie/versions/2548.5/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..d0b59bc --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4201 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Parallel sessions and worktrees + +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The syntax is: + +```text +/demo [what to demo] +``` + +The argument is free‑form natural language describing what you want to see. +Everything after `/demo ` is passed to the demo agent verbatim. + +### With no arguments + +```text +/demo +``` + +If you don't pass anything, `/demo` **picks up the previous context of the +current session automatically** — the messages you exchanged, the files +Junie touched, the task it just finished. You don't have to repeat what was +done; the demo agent already sees it. Junie then demos whatever stands out +from that history. If nothing stands out — for example you've just opened +a fresh project — Junie demos the app's main functionality. + +This is the most common way to use `/demo`: you've just had Junie implement +or fix something, and you want to *see* it working before you commit. Just +type `/demo` and hit Enter. + +### With a specific request + +```text +/demo show the new dark-theme toggle in Settings +/demo open the search dialog and find 'TODO' +/demo log in as user@example.com and open the profile page +``` + +The more concrete the request, the tighter the demo. A request like +`/demo show X` is treated as self‑contained — Junie won't go hunting through +git history to find unrelated context. + +### Demoing a specific feature from scratch + +```text +/demo the file-tree drag-and-drop in the sidebar +``` + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly. Junie will resolve how to reach it (menu item, hotkey, +URL, etc.) and walk through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +``` + +Junie picks up the change from the current session, opens the search box, +types several characters, and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +/demo open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Tell Junie directly in the request: `/demo open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2548.5/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2548.5/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..2848b1f --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo ` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | diff --git a/junie/versions/2548.5/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2548.5/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..9e90429 --- /dev/null +++ b/junie/versions/2548.5/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,169 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2651.3/skills/demo-setup/SKILL.md b/junie/versions/2651.3/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2651.3/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2651.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2651.3/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2651.3/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/BYOK.md b/junie/versions/2651.3/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..37b28ac --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,242 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..ebd1a63 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,197 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2651.3/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2651.3/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..a271ac9 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..a68fa1d --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,113 @@ +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..43827f0 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,162 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..298351f --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,487 @@ +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..d241854 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..16fed04 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,344 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2651.3/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2651.3/skills/junie-cli-docs/SKILL.md b/junie/versions/2651.3/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..68da854 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4233 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Parallel sessions and worktrees + +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2651.3/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2651.3/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..5560486 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | diff --git a/junie/versions/2651.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2651.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..9e90429 --- /dev/null +++ b/junie/versions/2651.3/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,169 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2651.4/skills/demo-setup/SKILL.md b/junie/versions/2651.4/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2651.4/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2651.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2651.4/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2651.4/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/BYOK.md b/junie/versions/2651.4/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..37b28ac --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,242 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..ebd1a63 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,197 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2651.4/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2651.4/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..a271ac9 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..a68fa1d --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,113 @@ +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..43827f0 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,162 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..298351f --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,487 @@ +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..d241854 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..16fed04 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,344 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2651.4/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2651.4/skills/junie-cli-docs/SKILL.md b/junie/versions/2651.4/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..68da854 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4233 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Parallel sessions and worktrees + +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2651.4/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2651.4/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..5560486 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | diff --git a/junie/versions/2651.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2651.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..9e90429 --- /dev/null +++ b/junie/versions/2651.4/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,169 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/junie/versions/2651.6/skills/demo-setup/SKILL.md b/junie/versions/2651.6/skills/demo-setup/SKILL.md new file mode 100644 index 0000000..6d57347 --- /dev/null +++ b/junie/versions/2651.6/skills/demo-setup/SKILL.md @@ -0,0 +1,138 @@ +--- +name: demo-setup +description: "Fill in a project's `/demo` configuration by inspecting the project: complete the `.junie/vms//Dockerfile` and the launch command in `.junie/demo.md`. TRIGGER when: the user asks to set up, configure, or finish `/demo`; the user asks you to fill in `.junie/demo.md` or a `.junie/vms/*/Dockerfile`; a first `/demo` run just seeded starter files and aborted. DO NOT TRIGGER when: `/demo` is already configured and the user only wants to run it, or when editing application code unrelated to demo setup." +--- + +# Setting up `/demo` for a project + +`/demo` drives the project's app inside a VM and records it. When a project has +no demo configuration, two starter files are seeded: + +- `.junie/demo.md` — the guide the demo agent reads before driving the app. +- `.junie/vms/template-vm/Dockerfile` — the VM image the app runs in. + +The user has already agreed to let you set this up. Full reference: +https://junie.jetbrains.com/docs/junie-cli-demo.html + +## The algorithm — follow it in order + +> **1. Research** — inspect the repo and form your best candidate launch command. +> **2. Confirm with the user** — show that candidate and ask. Write NOTHING yet. +> **3. Only then do it** — write `demo.md` with the confirmed command, then the Dockerfile. + +This is a hard sequence, not a suggestion. **Never modify any file without the +user confirming the change first.** Do not edit `demo.md` or the Dockerfile +until step 2 is done and the user has approved what you intend to write. Your +first file edit must come *after* the user has answered, never before. If you +catch yourself about to edit a file without an explicit confirmation — stop and +ask first. + +## 1. Find the candidate launch command + +Inspect the repo and form your best candidate for how to start the app: + +- **The dev/start command** — `scripts` in `package.json` (`dev`, `start`, + `preview`), or the equivalent for the project's stack. This is the field that + breaks the demo when wrong, so it's the thing to get right. +- **The runtime & package manager** — from the lockfile / manifest + (`pnpm-lock.yaml`, `yarn.lock`, `requirements.txt`, `pyproject.toml`, `go.mod`, + `Gemfile`, etc.). +- **The port** — from the script, framework default, or config. The agent needs + it for the health check. + +Be skeptical of scripts you find (`start-*.sh`, `run.sh`, Makefile targets): +one may exist for the project's own infrastructure, not for launching the app +the demo should show. Don't assume a script is the launch command just because +it looks like one. + +## 2. Propose the command and get the user's feedback + +**Do not write anything yet.** Present your candidate launch command (and the +port) to the user and ask them to confirm or correct it — use your ask-the-user +tool. Make clear it's a guess from inspecting the repo, not a fact. + +Only proceed once the user has confirmed or given you the right command. If they +correct it, use their command verbatim. The point of this step is that you reach +step 3 *knowing* what to run, instead of committing a best guess. + +## 3. Write `demo.md` with the confirmed command + +`demo.md` documents **only how to launch the app**, nothing else (no auth keys, +licenses, or unrelated setup — those belong in VM scripts or mounts). Fill: + +- **`vm:`** — the VM template directory name (default `template-vm`). +- **The launch command** under `## Running inside the VM` — the command the user + confirmed, run from `/workspace`. **Background it** (`&` or `nohup … &`) so the + agent can proceed, and bind to `0.0.0.0` if the framework defaults to + localhost-only. + +Delete the seeded explanatory HTML comments once the file is filled in. + +Example body: + +```markdown +vm: template-vm + +## Running inside the VM + +Install deps and start the dev server (Nuxt, port 3000): + + pnpm install + pnpm dev --host 0.0.0.0 & +``` + +## 4. Derive the Dockerfile from that command + +Now that the launch command is settled, make the VM able to run it. The template +extends the official demo base image: + +```dockerfile +FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 +``` + +The base **already ships Chromium, Node.js, xterm, a window manager, and an +ffmpeg recorder**. Rules: + +- **Only add layers on top of the base. Never replace the `FROM` line.** Add + only the runtimes/packages the confirmed command actually needs that the base + lacks (e.g. a specific Python, a pinned Node via corepack, system libs). +- For a plain Node/JS app the base is often enough — leave the Dockerfile as-is + rather than adding noise. +- If the command needs services or tooling the base can't provide (a Docker + daemon, a database, a multi-service orchestrator), that won't work in the VM — + go back to the user rather than papering over it. + +## 5. Build the image to verify the Dockerfile + +**If you added any layers to the Dockerfile** (a `RUN`, `COPY`, extra runtime, +etc.), build it now so a mistake — a wrong package name, an unavailable apt +package — surfaces here instead of failing later when the user runs `/demo`. +`/demo` builds with the project root as the build context and the template's +Dockerfile, so reproduce that exactly, from the project root: + + DOCKER_BUILDKIT=1 docker build -f .junie/vms//Dockerfile -t junie-demo--verify . + +- If the build **fails**, only fix it when the cause is clear and your fix is + certain (e.g. an obviously wrong package name). Otherwise **don't keep guessing + and rebuilding** — that's the same guesswork this skill exists to avoid. After + one or two confident fixes at most, if it still won't build or you're unsure + why, stop, show the user the build error, and ask them how to proceed. Either + way, do not touch the launch command — the user already confirmed it. +- If `docker` isn't available or the base image can't be pulled (the base lives + in a registry that may need auth), **don't treat that as a Dockerfile error** — + skip the build, say you couldn't verify it and why, and still hand back. +- If you added **no** layers (the Dockerfile is the untouched base), skip this — + there's nothing of yours to validate and `/demo` pulls the base anyway. + +This only builds the image to validate it. It is not running the demo — do not +start the VM or record anything. + +## 6. Hand back + +- Both essentials present: `vm:` resolves to an existing `.junie/vms//` + directory, and the confirmed launch command exists under `## Running inside + the VM`. +- Summarize what you set up (and whether the image built), then tell the user to + review the two files and re-run `/demo` — do not run `/demo` yourself. The + `.junie/` folder is the user's; the generated config is a starting point they + confirm. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md b/junie/versions/2651.6/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md new file mode 100644 index 0000000..0b1b27a --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Action-Allowlist-Junie-CLI.md @@ -0,0 +1,94 @@ +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` \ No newline at end of file diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Agent-Skills.md b/junie/versions/2651.6/skills/junie-cli-docs/Agent-Skills.md new file mode 100644 index 0000000..c2c76bf --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Agent-Skills.md @@ -0,0 +1,403 @@ +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/BYOK-OpenRouter.md b/junie/versions/2651.6/skills/junie-cli-docs/BYOK-OpenRouter.md new file mode 100644 index 0000000..8eeec2c --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/BYOK-OpenRouter.md @@ -0,0 +1,38 @@ +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/BYOK.md b/junie/versions/2651.6/skills/junie-cli-docs/BYOK.md new file mode 100644 index 0000000..c4a6c37 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/BYOK.md @@ -0,0 +1,36 @@ +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LM-Studio.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LM-Studio.md new file mode 100644 index 0000000..648a7da --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LM-Studio.md @@ -0,0 +1,55 @@ +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LiteLLM.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LiteLLM.md new file mode 100644 index 0000000..e39c770 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-LiteLLM.md @@ -0,0 +1,67 @@ +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-Ollama.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-Ollama.md new file mode 100644 index 0000000..6d9cff3 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-Ollama.md @@ -0,0 +1,63 @@ +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-models.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-models.md new file mode 100644 index 0000000..37b28ac --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-LLM-models.md @@ -0,0 +1,242 @@ +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-proxies.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-proxies.md new file mode 100644 index 0000000..ebd1a63 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-proxies.md @@ -0,0 +1,197 @@ +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Custom-slash-commands.md b/junie/versions/2651.6/skills/junie-cli-docs/Custom-slash-commands.md new file mode 100644 index 0000000..3876c5a --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Custom-slash-commands.md @@ -0,0 +1,61 @@ +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Guidelines-and-memory.md b/junie/versions/2651.6/skills/junie-cli-docs/Guidelines-and-memory.md new file mode 100644 index 0000000..730c3f8 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Guidelines-and-memory.md @@ -0,0 +1,127 @@ +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) \ No newline at end of file diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md new file mode 100644 index 0000000..9477586 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Debug-Mode.md @@ -0,0 +1,65 @@ +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-EAP.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-EAP.md new file mode 100644 index 0000000..61dcee7 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-EAP.md @@ -0,0 +1,68 @@ +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Extensions.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Extensions.md new file mode 100644 index 0000000..ea59149 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Extensions.md @@ -0,0 +1,167 @@ + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md new file mode 100644 index 0000000..1aa722a --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-JetBrains-IDE-integration.md @@ -0,0 +1,119 @@ +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md new file mode 100644 index 0000000..f1fda29 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-MCP-configuration.md @@ -0,0 +1,136 @@ + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. \ No newline at end of file diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md new file mode 100644 index 0000000..d8579b7 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Plan-Mode.md @@ -0,0 +1,92 @@ +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md new file mode 100644 index 0000000..a271ac9 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Remote-Mode.md @@ -0,0 +1,108 @@ +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Worktrees.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Worktrees.md new file mode 100644 index 0000000..a68fa1d --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-Worktrees.md @@ -0,0 +1,113 @@ +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-configuration.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-configuration.md new file mode 100644 index 0000000..43827f0 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-configuration.md @@ -0,0 +1,162 @@ +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-demo.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-demo.md new file mode 100644 index 0000000..298351f --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-demo.md @@ -0,0 +1,487 @@ +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-hooks.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-hooks.md new file mode 100644 index 0000000..d241854 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-hooks.md @@ -0,0 +1,376 @@ +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-subagents.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-subagents.md new file mode 100644 index 0000000..10b316e --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI-subagents.md @@ -0,0 +1,183 @@ +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` \ No newline at end of file diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI.md new file mode 100644 index 0000000..16fed04 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-CLI.md @@ -0,0 +1,344 @@ +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Junie-Review-Agent.md b/junie/versions/2651.6/skills/junie-cli-docs/Junie-Review-Agent.md new file mode 100644 index 0000000..ce4bbd7 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Junie-Review-Agent.md @@ -0,0 +1,85 @@ +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. \ No newline at end of file diff --git a/junie/versions/2651.6/skills/junie-cli-docs/SKILL.md b/junie/versions/2651.6/skills/junie-cli-docs/SKILL.md new file mode 100644 index 0000000..68da854 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/SKILL.md @@ -0,0 +1,4233 @@ +--- +name: junie-cli-docs +description: Complete documentation for using Junie CLI in the terminal. Use this skill when the user asks about Junie itself, its features, configuration, where agent sessions/settings/logs are located, or CLI commands. +--- + +# Junie CLI documentation + +Use this skill when you need complete Junie CLI documentation. +The full documentation bundle is embedded below + +**IMPORTANT**: The agent cannot directly execute Junie CLI commands (such as `new`, `usage`, `model`, etc.). +The agent can only suggest to the user which commands to run. + +## Full documentation + +### Quickstart + +# Quickstart + + + +**Junie CLI** is the agentic coding tool by JetBrains that provides an interactive terminal interface for developers to +review, write, and modify code. + + +Junie CLI is available on Linux, macOS, and Windows. + + +## Step 1: Install Junie CLI {level="3"} + +In the terminal or command prompt of your choice, run: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +[//]: # (EAP channel:) + +[//]: # (curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash) + +## Step 2: Start Junie in your project {level="3"} + +Navigate to the root directory of the project where you want to use Junie CLI and run `junie`: + +```console +cd /path/to/your/project +``` + +```sh +junie +``` + +## Step 3: Authenticate {level="3"} + +On the Junie welcome screen, select one of the available authentication options: + +* **Log in with your JetBrains Account** + + Use Junie CLI as part of your subscription plan with JetBrains. When selecting this option, you'll be redirected to +the JetBrains Junie login page in your browser. + +* **Use `JUNIE_API_KEY`** + + Run Junie CLI with usage-based billing. When selecting this option, you'll be prompted to provide an access +token. To generate your `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* **[Bring Your Own Key (BYOK)](BYOK.md)** + + Use your own API keys or OAuth tokens from Anthropic, OpenAI, Google, or other third-party LLM providers. + Junie CLI uses these API keys to send requests to LLMs directly without requiring a JetBrains AI subscription. + + BYOK can be used on its own or together with JetBrains Account authorization or Junie API key. + If a model is available through both the BYOK API key and JetBrains AI subscription, the requests are billed to your BYOK provider directly. + +[//]: # (> By authenticating with Junie CLI, you agree to [Junie Terms of Service](https://junie.jetbrains.com/tos-eap).) + +[//]: # (> {style="note"}) + +## Step 4: Type your prompt {level="3"} + +Type the prompt in the interactive CLI, for example: + +```Console +> give me an overview of this codebase +``` + +Use `@` to attach a file or folder from the current project to the request context. +To see the list of available slash commands and use them, type `/`. + +### Real-time follow-ups + +You can type follow-up prompts while Junie CLI is working on the task without waiting for it to finish. +The added clarifications are appended to the initial prompt and taken into account by the agent immediately. + +### Reference files and directories + +Use `@` to quickly reference files or directories in your prompt. + +[//]: # (When you include file paths directly in the prompt using the `@` syntax, the CLI now validates those paths and sends only the ones that actually exist on your machine.) + +[//]: # () +[//]: # (- Non-existent paths are ignored silently and are not attached to the request.) + +[//]: # (- Existing paths are attached and will be available to Junie during task processing.) + +[//]: # (- Use your OS-native path format (the CLI checks paths using the local filesystem).) + +![](reference_files_and_folders.png){width="706"} + +You can also drag and drop files and images into the terminal window to reference them. + +### Image inputs + +Drag and drop or reference screenshots or design specs in the prompt for Junie CLI to read the image details. +Junie CLI accepts all common image formats such as PNG and JPEG. + +### Search the prompt history + +Junie CLI preserves your prompt history across all sessions and application runs. + +To search the prompt history, use `Ctrl+R`, and then navigate through the results using Up and Down arrow keys. + +## Slash commands and shortcuts + +Slash commands allow you to access various Junie CLI features directly from the prompt. +Type `/` in the prompt to see and use the [available slash commands](Slash-commands.md). + +Some built-in slash commands accept user prompts as arguments. For example, `/new fix tests` [starts another live session](#clear-up-session-context) with +`fix tests` in the prompt, and `/plan refactor commands` enables [plan mode](#plan-mode) and submits `refactor commands` immediately. + +In addition to the built-in commands, you can [add custom slash commands](Custom-slash-commands.md) for frequently used prompts and +repetitive tasks. + +To see all available shortcuts, type `?`. + +## Run shell commands + +You can run shell commands without leaving Junie CLI by prefixing it with `!`, for example: + +``` +!ls -la +``` + +## Command approval + +For running potentially sensitive actions, such as executing most of the terminal commands, +editing files outside the project, or invoking MCP tools, Junie CLI will ask for approval from the user. + +### Action Allowlist + +When Junie CLI stops for user approval, you can select the **→ Always allow** option to add +the indicated command to the Action Allowlist. Once on the Action Allowlist, the command will always be executed +without user approval in the future Junie CLI runs. + +![](action_allowlist_junie_cli.png){width="706"} + +The full list of allowed commands and command patterns is stored in the `~/.junie/allowlist.json` file. You can also +edit this file manually to add or remove allowed or restricted commands and patterns. For details, see +[Action Allowlist configuration](Action-Allowlist-Junie-CLI.md). + +### Brave mode + +Brave mode controls how much Junie CLI relies on user approval before running potentially sensitive actions. +It has three levels that you can cycle through with the `/brave` slash command or the `Ctrl+B` shortcut: + +* **Off** – Junie CLI asks for approval for every potentially sensitive action that is not on the Action Allowlist. + This is the most conservative behavior. +* **Auto** – Junie CLI classifies terminal commands with a safety check and automatically approves the ones it + considers safe, while still asking for approval for risky or unrecognized commands and for other sensitive actions. +* **On** – Junie CLI executes all potentially sensitive actions without user approval. + +![](brave_mode_on.png){width="706"} + +## Plan mode + +In plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. Toggle plan mode with the `Shift+Tab` shortcut or the `/plan` slash command. + +You can also start Junie CLI directly in plan mode using the `--plan` flag: + +```bash +junie --plan +junie --prompt "Refactor the commands module" --plan +``` + +For details, see [Plan mode](Junie-CLI-Plan-Mode.md). + +## Debug mode + +In debug mode, Junie CLI acts as an AI debugging assistant that manages breakpoints, inspects runtime state, and +evaluates expressions against a live debugger session in a connected JetBrains IDE. Toggle debug mode with the +`Shift+Tab+Tab` shortcut or the `/debug` slash command. For details, see [Debug Mode](Junie-CLI-Debug-Mode.md). + +[//]: # (## Terminal mode) + +[//]: # (You can run shell commands directly within Junie to inspect your project or run tests:) + +[//]: # (1. Type `!` followed by your command (e.g., `!./gradlew test`).) + +[//]: # (2. Junie will execute the command and display the output.) + +[//]: # (3. You can also type `/terminal` to enter a persistent terminal session.) + +## Local code review {id="local-code-review"} + +Use the `/review` slash command to run a code review of your local changes before you commit them. Junie CLI uses +the same review backend as [automated code reviews](Automated-code-reviews.md) on GitHub, so the feedback you get +locally is consistent with what would be reported on a pull request. + +When you run `/review`, Junie CLI detects the git state of the project and offers a wizard with only the +review targets that make sense in the current state: + +- **From Main**: review your current branch against `main`. Shown only when a `main` branch exists and you are + not currently on it (there is nothing to compare if you are already on `main`). +- **Last Commit**: review the diff of the most recent commit. Always available as long as the project has at + least one commit. +- **Unstaged Changes**: review changes that are not yet staged. Shown only when there are actual unstaged + changes in the working tree. + +Pick an option, and Junie CLI will start a review task that comments on the selected diff. + +![](review_wizard.png){width="706"} + +After the review is complete, Junie CLI presents the findings and lets you accept or dismiss individual comments. + +![](review_results.png){width="706"} + +> `/review` requires the current project to be a Git repository. If no `.git` directory is found, Junie CLI reports +> that no git repository was detected and does not start the wizard. +> {style="note"} + +## Manage your account + +Use the `/account` command to manage your credentials and API keys: + +* Select **Junie Account** to authenticate with Junie CLI via JetBrains Account or a Junie API key. + + To generate a `JUNIE_API_KEY` access token, go to [junie.jetbrains.com/cli](https://junie.jetbrains.com/cli). + +* Select **Bring Your Own Key (BYOK)** to add API keys for LLM providers like OpenAI, Anthropic, Google, or xAI. + + > BYOK can be used on its own or together with JetBrains Account authorization. + > If a model is available through both the BYOK API key and JetBrains AI subscription, + > the requests are billed directly to the model provider without consuming credits from your JetBrains account. + +## Manage your session + +### Start another session {id="clear-up-session-context"} + +Use `/new` to start another live session in the same interactive Junie instance. Existing live sessions keep running +in the background and stay available in Task history. + +Use `/new ` to start another session with the prompt text already filled in. + +### View session transcript + +To access the full transcript of the current session, including all previous prompts and the agent output, +use the `Ctrl+O` shortcut. +By default, Junie opens a continuously updated `transcript.md` file stored next to the session's `events.jsonl` file. +Subagent transcripts are stored in the session's `subagents` folder and `Ctrl+O` opens the selected subagent transcript +while you are viewing its task. + +Use `/settings` and change **Show transcript** to **Terminal** to open the built-in Transcript view instead. +In that view, use `Esc` to return to the main view. + +### Switch sessions and resume history + +To search session history, switch between live sessions, or resume a saved session from a previous run, use `/history` +to open **Task history**. + +Junie stores the full session context, including LLM usage data and the history of user prompts and agent responses, +for the last 10 sessions. + +For details on running several sessions and isolating their file changes, see [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). + +### Quit the session + +To exit the Junie CLI interactive mode without losing login credentials, use `/quit`. +Alternatively, you can exit Junie CLI by using `Ctrl+C` twice. + +### Continue the session in a browser + +Use `/remote` to share the running Junie CLI session with the Junie web app and continue working on the same task +from another device. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). + +## Model and effort {id="model-and-effort"} + +Use `/model` to select the LLM and, for supported models, the reasoning **effort level** used for the current +session. `Default` is the recommended pre-selected option that uses a dynamically set model with the best +price-quality ratio. + +The selection of available models depends on your [authentication method](Junie-CLI.md#step-3-authenticate) with +Junie CLI. With BYOK, only the provider-specific models are available. + +![](model_selection_with_effort.png){width="706"} + +### Effort level + +For models that support adjustable reasoning effort (for example, recent Claude, GPT-5, and Gemini models), you can +pick how hard the model thinks before answering. The set of supported effort levels (such as `Low`, `Medium`, +`High`, `XHigh`, `Max`) depends on the selected model. + +You can change the effort level in two ways: + +- Use the `/model` command and pick an effort level alongside the model. +- Use the dedicated `/effort` command to change only the effort level for the current model. + +![](effort_level_selection.png){width="706"} + +You can also set the default effort level for new sessions with the `--effort ` CLI flag or the +`JUNIE_EFFORT` environment variable. For details, see [Model selection](Junie-CLI-Model-selection.md). + +> We recommend keeping the default model and effort settings. Higher effort levels do not always produce noticeably +> better results, but they can cost significantly more and make the model take noticeably longer to respond as it +> spends more time reasoning. Increase the effort only when you have observed that a specific task benefits from it. +> {style="note"} + +## Token usage and costs + +The `/usage` command shows the cost breakdown for the current session, including token usage, used models, and remaining balance. + +![](check_session_cost.png){width="706"} + +## Extend Junie CLI + +* [Model Context Protocol (MCP)](Junie-CLI-MCP-configuration.md) +* [](Agent-Skills.md) +* [Subagents](Junie-CLI-subagents.md) +* [](Custom-slash-commands.md) +* [Guidelines and memory](Guidelines-and-memory.md) + +## Non-interactive (headless) mode + +You can run Junie CLI in headless mode, that is, programmatically without interactive UI, in CI/CD environments +and build pipelines. + +To add Junie to your CI/CD script: + +```bash +# Install Junie CLI +curl -fsSL https://junie.jetbrains.com/install.sh | bash + +# Authenticate and run a task +junie --auth="$JUNIE_API_KEY" "Fix any failing tests" + +# Run a code review of the latest commit +junie --auth="$JUNIE_API_KEY" --review +``` +The `junie` command takes [options](Parameters.md) and [environment variables](Parameters.md#environment-variables). + +For more information and examples, see [Headless mode](Junie-headless.md). + +## Junie in CI/CD pipelines + +* [Junie GitHub Action](Junie-on-GitHub.md) +* [Junie GitLab CI/CD](Junie-GitLab-CI-CD.md) + +### Bring Your Own Key (BYOK) + +# Bring Your Own Key (BYOK) + +Junie CLI supports using your own API keys from third-party LLM providers. Instead of relying on a JetBrains AI subscription, you can connect directly to providers like OpenAI, Anthropic, Google, xAI, OpenRouter, or GitHub Copilot. + +## How it works + +With BYOK, Junie sends requests to LLMs using your API key directly. All usage is billed by the provider — no JetBrains AI subscription is required. + +You can also combine BYOK with a JetBrains Account or Junie API key. If a model is available through both your BYOK key and your JetBrains subscription, the BYOK key takes priority, and the requests are billed to your provider. + +## Connect an external LLM provider + +1. Run the `/account` slash command in an active Junie session, or select **Use external LLM providers** on the welcome screen. + + ![Use external LLM providers](byok_use_external_llm.png){width="600"} + +2. Select a provider from the list and paste your API key when prompted. + + ![Select a provider](byok_select_openrouter.png){width="600"} + +3. Once connected, use `/model` to see and switch between available models. + +## Supported providers + +| Provider | Key type | +|---|---| +| OpenAI | API key | +| Anthropic | API key | +| Google | API key | +| xAI | API key | +| OpenRouter | API key | +| Custom Profiles | JSON file | + + +For step-by-step setup instructions, see the provider-specific guides below. +- [Connect a custom LLM provider](Custom-LLM-models.md) + +### OpenRouter + +# OpenRouter + +OpenRouter is a unified API that gives you access to models from multiple providers — including Anthropic, OpenAI, Google, xAI, and others — through a single API key. + +## Prerequisites + +- An OpenRouter account. Sign up at [openrouter.ai](https://openrouter.ai) if you don't have one. +- An OpenRouter API key. Generate one from your [OpenRouter dashboard](https://openrouter.ai/keys). + +## Set up OpenRouter in Junie + +1. Start Junie in your project directory: + + ```sh + junie + ``` + +2. Run the `/account` command and select **Use external LLM providers**. + + ![Select Use external LLM providers](byok_use_external_llm.png){width="600"} + +3. Select **OpenRouter** from the provider list. + + ![Select OpenRouter](byok_select_openrouter.png){width="600"} + +4. Paste your OpenRouter API key when prompted. + +## Select a model + +Once connected, run `/model` to see the available models and select one: + +![Available models via OpenRouter](byok_openrouter_models.png){width="600"} + +The model list shows models available through your OpenRouter key, along with pricing info. Use the arrow keys to navigate and press Enter to select a model. + +## Additional resources + +- [OpenRouter guide for coding agents](https://openrouter.ai/docs/guides/guides/coding-agents/junie) + +### Early Access Program (EAP) + +# Early Access Program (EAP) + + + +The Early Access Program (EAP) gives you access to pre-release versions of Junie CLI with the latest features and improvements +before they are generally available. + +> By participating in the EAP, you agree to the [JetBrains Junie Terms of Service](https://www.jetbrains.com/legal/docs/terms/jetbrains-junie/), +> including the EAP-specific terms. "EAP" means any of the pre-release versions of the product made available under these Terms +> as determined by JetBrains. +> {style="note"} + +## Join the EAP {id="join-eap"} + +The EAP is free to join and includes a monthly usage quota at no cost. To request access, fill out the [Contact Form](https://intellij-support.jetbrains.com/hc/en-us/requests/new?ticket_form_id=66731). + +We are actively looking for developers working with the following languages and technologies: + +- C and C++ +- PHP +- Rust +- Java + +If you work with any of these languages, we especially encourage you to apply. + +## Install the Early Access version {id="install-eap"} + +To install the Early Access version of Junie CLI, run the following command in your terminal: + + + + curl -fsSL https://junie.jetbrains.com/install-eap.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install-eap.ps1')" + + + +To verify the installation, restart your shell if needed and run: + +junie --version + + +## Switch between EAP and stable versions {id="switch-versions"} + +To switch back to the stable version, remove the local Junie launcher first: + + + + rm ~/.local/bin/junie + + + Remove-Item "$HOME\.local\bin\junie.bat" + + + +Then install the stable version using the standard installation command: + + + + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + + powershell -NoProfile -ExecutionPolicy Bypass -Command "iex (irm 'https://junie.jetbrains.com/install.ps1')" + + + +For more details on the standard installation process, see the [Quickstart](Junie-CLI.md). + +### Integration with JetBrains IDEs + +# Integration with JetBrains IDEs + + + +This page describes how Junie CLI integrates with JetBrains IDEs, what products are supported, which features depend on the JetBrains IDE connection, and how to inspect the connection with `/ide`. + +## What JetBrains IDE integration does + +When JetBrains IDE integration is available, Junie CLI can connect to the Junie plugin running inside a JetBrains IDE for the same project and use JetBrains IDE awareness for that session. + +This improves features that depend on project understanding inside the IDE, such as symbol-aware search, safer code edits, code inspections, test workflows, and product-specific actions. + +JetBrains IDE integration requires the Junie IDE plugin. For installation and setup details, see [Junie IDE plugin](Junie-IDE-plugin.md). + +JetBrains IDE integration is passive from the CLI side: + +- The IDE plugin becomes available automatically when you open the same project. +- The CLI discovers running IDE sessions automatically. +- The CLI selects the best matching JetBrains IDE for the current working directory. +- The CLI connects to the JetBrains IDE only when IDE-backed features are needed or when you inspect the state with `/ide`. + +> Junie CLI currently supports only JetBrains IDEs for this integration. It does not connect to non-JetBrains editors or IDEs. +> {style="note"} + +## Supported JetBrains IDEs + +The current IDE discovery implementation supports these JetBrains IDEs: + +- ![CLion](CLion_icon.png){width="25"} [CLion](https://www.jetbrains.com/clion/) +- ![GoLand](GoLand_icon.png){width="25"} [GoLand](https://www.jetbrains.com/go/) +- ![IntelliJ IDEA](IntelliJ_IDEA_icon.png){width="25"} [IntelliJ IDEA](https://www.jetbrains.com/idea/) +- ![PhpStorm](PhpStorm_icon.png){width="25"} [PhpStorm](https://www.jetbrains.com/phpstorm/) +- ![PyCharm](PyCharm_icon.png){width="25"} [PyCharm](https://www.jetbrains.com/pycharm/) +- ![Rider](Rider_icon.png){width="25"} [Rider](https://www.jetbrains.com/rider/) +- ![RubyMine](RubyMine_icon.png){width="25"} [RubyMine](https://www.jetbrains.com/ruby/) +- ![RustRover](RustRover_icon.png){width="25"} [RustRover](https://www.jetbrains.com/rust/) +- ![WebStorm](WebStorm_icon.png){width="25"} [WebStorm](https://www.jetbrains.com/webstorm/) + +Support means that the CLI can detect installed and running instances of these products and match them to the current +project when the [Junie plugin](Junie-IDE-plugin.md) is available. + +## What features are affected + +The JetBrains IDE connection affects user-visible features that benefit from the IDE understanding your project. + +In practice, JetBrains IDE integration can improve tasks such as: + +- Code search with symbol awareness and project indexes. +- Code edits that use the IDE understanding of your project structure. +- Code inspections and structure-aware analysis. +- Test discovery and test execution from the IDE project context. +- Refactorings and other project-aware changes. +- Product-specific workflows in IDEs such as CLion or Rider. + +JetBrains IDE integration also improves `@` completions in the prompt. When the IDE is connected, Junie CLI can suggest not only project files and folders, but also classes and symbols known to the connected JetBrains IDE. + +The CLI can also use JetBrains IDE context for the session, such as which files are currently open in the IDE. + +If no JetBrains IDE is connected, Junie CLI can still work, but IDE-backed capabilities are unavailable. + +## Requirements + +For JetBrains IDE integration to work: + +- Open the target project in a supported JetBrains IDE. +- Make sure the Junie plugin is installed and running. +- Open the same project so the IDE integration can start. +- Run Junie CLI from the same project or a child directory of that project. + +If the project paths do not match, the CLI will not select that IDE session. + +## Use the `/ide` command + +Use `/ide` in Junie CLI to inspect the current JetBrains IDE integration state. + +What `/ide` does: + +- Lists running IDEs and their states. +- Allows you to switch between multiple IDEs and projects. +- Helps install the plugin if it is missing. + +### Possible states + +| State | Meaning | +|------|---------| +| `Connected` | The CLI is connected to that JetBrains IDE and can use JetBrains IDE-backed features | +| `Connecting…` | The CLI found a matching JetBrains IDE and is opening the connection | +| `Auth required` | The JetBrains IDE session is running, but the current connection is no longer authorized | +| `Error` | The JetBrains IDE was found, but the connection failed for another reason | +| `Ready` | The Junie plugin for that JetBrains IDE is available and can be selected | +| `Missing` | The Junie plugin is not installed for that JetBrains IDE | +| `Not responding` | The Junie plugin is installed, but it is not responding | +| `Unsupported` | That JetBrains IDE version is too old for Junie IDE integration | +{width="706"} + +### Notes + +- `/ide` is a status command. It does not start a JetBrains IDE or enable JetBrains IDE integration by itself. +- The available features depend on the connected JetBrains IDE, the open project, and which capabilities are available in that session. +- If several JetBrains IDEs are running, the CLI prefers the one whose project path matches the current working directory most closely. +- `/ide` reports only JetBrains IDE integration state. It does not represent support for other editors or IDEs. + +## Troubleshooting + +| Problem | What to check | +|---------|---------------| +| `/ide` shows `Missing` | Install the Junie plugin for that JetBrains IDE, then wait a moment and run `/ide` again | +| `/ide` shows `Auth required` | Restart the JetBrains IDE, then run `/ide` again. If the problem stays, inspect `~/.junie/logs/junie.log` | +| `/ide` shows `Not responding` | Check whether the Junie plugin is enabled and update it to the latest version if needed | +| `/ide` shows `Error` | Check `~/.junie/logs/junie.log` for the connection error and verify that the JetBrains IDE project path matches the CLI working directory | +| `/ide` shows `Unsupported` | Update that JetBrains IDE to version `2026.1` or newer | +| `/ide` shows few available features after connecting | Verify that the JetBrains IDE session is fully loaded for that project and that the required JetBrains IDE features are available for that product and project | +{width="706"} + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Junie for ACP clients](Junie-CLI-ACP.md) +- [Junie IDE plugin](Junie-IDE-plugin.md) + +### config.json + +# config.json + +Junie CLI can load settings from JSON configuration files in addition to command-line flags and environment variables. +Configuration files are useful when you want to keep shared project defaults in the repository or define personal defaults once for all projects. + +## Default configuration locations + +By default, Junie CLI looks for `config.json` in these locations: + +* **User scope**: `~/.junie/config.json` +* **Project scope**: `/.junie/config.json` + +The project-level configuration is intended for settings that should be shared with the whole team. +The user-level configuration is intended for personal defaults on your machine. + +## Project trust + +Interactive Junie CLI sessions ask for a trust decision before loading project configuration from a project that has no valid stored trust marker: + +1. **Keep untrusted** — continue with isolated temporary project Junie storage. +2. **Trust this project** — trust only the canonical project directory. +3. **Trust all projects in ``** — trust the canonical parent directory and projects below it. + +Junie canonicalizes project and scope paths and resolves symbolic links before evaluating trust. Exact trust applies only to that project. Parent trust applies to projects at or below the displayed canonical parent, using path-aware containment rather than string-prefix matching. A valid exact or ancestor marker lets a matching project start without another prompt. + +An untrusted project remains the workspace for ordinary file operations, but Junie does not implicitly load project configuration, MCP servers, hooks, extensions, models, plans, demos, custom agents or commands, skills, root or project Junie guidelines, project memory, or automatic migration/onboarding sources. Instead, Junie uses a writable temporary project Junie directory outside the repository. MCP servers, skills, and commands added during the session use that directory and are removed when the CLI process closes. Global sources under Junie Home remain enabled. + +After the interactive UI opens an untrusted project, its startup header explains that project files remain available while project-provided Junie configuration is not loaded. + +Paths supplied explicitly through CLI options or environment variables, including `--config-location`, remain enabled because the user selected them deliberately. + +Junie stores only a project-trust authentication key in macOS Keychain, Windows Credential Manager, or Linux Secret Service. If native secure storage is unavailable or unusable, the key is kept in an owner-only `authentication-key` file inside the same trust directory instead, so your decision is remembered on headless machines and in containers. Each exact-project or parent-directory scope has a separate authenticated marker under `/trust`; the default location is `~/.junie/trust`. The marker contains its kind and canonical path, but cannot grant trust unless its integrity code matches that key. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for projects below it on the next CLI process. Keeping a project untrusted does not create a denial marker. + +If a marker still cannot be written and verified, the trust selection applies to the current run only, and Junie says so once so that you know it will ask again next launch. Neither the key nor trust markers are written to `settings.json` or the plaintext `secure_credentials.json` fallback. + +Interactive UI launches always resolve project trust and prompt when no valid exact-project or ancestor marker exists. Non-interactive JSON, ACP, and Gateway launches are always trusted: they cannot ask you for a decision, so they load project configuration without a prompt, a flag, or an environment variable. This keeps CI and other automated environments working without any extra setup. + +## Configuration precedence + +When the same setting is defined in multiple places, Junie resolves it in this order +(highest priority first): + +1. Command-line flags +2. User settings from `~/.junie/settings.json` +3. Project configuration from `/.junie/config.json` when the CLI project is trusted +4. User configuration from `~/.junie/config.json` + +For example, if `~/.junie/config.json` sets `"model": "sonnet"`, the project config sets `"model": "gpt"`, +and you run `junie --model opus`, the effective model is `opus`. + +## Add extra configuration files + +To load additional configuration files, use `--config-location`. +You can specify it multiple times: + +```bash +junie \ + --config-location /opt/company/junie/config.json \ + --config-location ./configs/junie.local.json +``` + +Explicit configuration locations are loaded even when the CLI project is untrusted. + +To disable loading from the default user and project locations, use `--config-default-locations false`. + +For CI, you can use the equivalent environment variables: + +| Environment variable | CLI equivalent | Description | +|---|---|---| +| JUNIE_CONFIG_LOCATION | --config-location | Additional configuration file paths. Can be specified multiple times. | +| JUNIE_CONFIG_DEFAULT_LOCATIONS | --config-default-locations | Enable or disable loading `config.json` from the default user and project locations. Defaults to `true`. | + +## Supported configuration fields + +The following JSON fields are currently supported in `config.json`: + +| Field | Description | +|---|---| +| `model` | Default model to use. For supported built-in model IDs and custom model profiles, see [Model selection](Junie-CLI-Model-selection.md) and [Custom LLM models](Custom-LLM-models.md). | +| `provider` | Default BYOK provider. For supported provider values, see [LLM providers](Junie-CLI-Model-selection.md#llm-providers). | +| `brave` | Enables brave mode by default. | +| `flags` | Additional feature flags. | +| `mcp-locations` | Extra folders where Junie should search for MCP configurations. | +| `mcp-default-locations` | Enable or disable the default MCP locations. | +| `skill-locations` | Extra folders where Junie should search for agent skills. | +| `skill-default-locations` | Enable or disable the default skill locations. | +| `command-locations` | Extra folders where Junie should search for custom slash commands. | +| `command-default-locations` | Enable or disable the default custom slash command locations. | +| `agent-locations` | Extra folders where Junie should search for custom agents. | +| `agent-default-location` | Enable or disable the default custom agent locations. | +| `model-locations` | Extra folders where Junie should search for custom model profiles. | +| `model-default-locations` | Enable or disable the default model locations. | +| `auto-update` | Enable or disable automatic update checks. | +| `guidelines-location` | Path to the guidelines file Junie should use. | +| `time-limit` | Default task time limit. | +| `byok` | Default BYOK API keys for supported providers. | +| `proxies` | Custom proxy endpoints for routing LLM traffic. | +| `hooks` | Shell commands to run on session lifecycle events. See [Hooks](Junie-CLI-hooks.md). | + +Relative paths in `config.json` are resolved relative to the folder that contains that configuration file. + +For safety, `hooks` from the default project configuration file are ignored. +Use `~/.junie/config.json` for personal hooks, or pass a hook config file explicitly with `--config-location`. + +## Example configuration file + +```json +{ + "model": "sonnet", + "provider": "anthropic", + "brave": false, + "flags": [], + "mcp-locations": ["./mcp", "./shared/mcp"], + "mcp-default-locations": true, + "skill-locations": ["./skills"], + "skill-default-locations": true, + "command-locations": ["./commands"], + "command-default-locations": true, + "agent-locations": ["./agents"], + "agent-default-location": true, + "model-locations": ["./models"], + "model-default-locations": true, + "auto-update": true, + "guidelines-location": "./team-guidelines.md", + "time-limit": 3600, + "byok": { + "anthropic": "sk-ant-...", + "openai": "sk-..." + }, + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://my-ingrazzio-instance.example.com", + "headers": ["X-Custom-Header: value"] + } + ], + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { "type": "command", "command": "aws sso login --profile dev" } + ] + } + ] + } +} +``` + +## How configuration combines with other features + +Configuration files control discovery for several other Junie CLI features: + +* [MCP configuration](Junie-CLI-MCP-configuration.md) +* [Agent skills](Agent-Skills.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Custom LLM models](Custom-LLM-models.md) +* [Guidelines and memory](Guidelines-and-memory.md) +* [Hooks](Junie-CLI-hooks.md) + +For the exact command-line flags, see [CLI reference](Parameters.md). + +### Action Allowlist + +# Add commands to Action Allowlist + +If [brave mode](Junie-CLI.md#brave-mode) is not explicitly enabled, Junie CLI will ask for user approval before +running terminal commands, MCP tools, and other [types of actions](Action-Allowlist.md#types-of-action-allowlist-rules) +that are considered to be sensitive by the coding agent. + +You can manually add or remove allowed commands by editing the `~/.junie/allowlist.json` file. + +There are three types of actions that can be allowed with the `allowlist.json` file: + +* `fileEditing`: editing files outside the project directory where Junie CLI is launched; editing build scripts outside + or inside the project directory. +* `executables`: running terminal commands, including execution of tests, running apps, or build actions. +* `mcpTools`: usage of Model Context Protocol (MCP) tools. +* `readOutsideProject`: reading files outside the current project directory where Junie CLI is launched. + +An example `allowlist.json` file looks as follows: + +```json +{ + "defaultBehavior": "ask", + "allowReadonlyCommands": true, + "rules": { + "fileEditing": { + "rules": [ + { + "prefix": "src/main/kotlin/", // The path is relative to the current project directory. For absolute paths, start with `/`. + "action": "allow" + } + ] + }, + "executables": { + "rules": [ + { + "prefix": "git", + "action": "allow" + }, + { + "pattern": "grep **", + "action": "allow" + }, + { + "pattern": "npm [iur]*", + "action": "ask" + } + ] + }, + "mcpTools": { + "rules": [ + { + "prefix": "github-server:", + "action": "allow" + } + ] + }, + "readOutsideProject": { + "rules": [ + { + "pattern": "/etc/**", + "action": "ask" + } + ] + } + } +} +``` + +Each rule must specify either a `prefix` or a `pattern`, along with an `action` (`allow` or `ask`). +Select the appropriate action type and edit its `rules` array: + +| Field | Description | +|-----------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `prefix` | Set a literal string to match all commands that start with it.

    For example, indicating a `git` prefix allows all `git` commands (`git status`, `git commit`, `git push`, etc.). | +| `pattern` | Set a pattern using wildcard characters (Glob syntax):
  • `*` – Matches zero or more arbitrary characters, except for the path separator `/`.
  • `**` – Matches zero or more arbitrary characters, including the path separator `/`.
  • `?` – Matches exactly one arbitrary character, except for the path separator `/`.
  • `[abc]` – Matches any single character from the characters listed in brackets.
  • `[!abc]` – Matches any single character except for the characters listed in brackets.
    •  | +| `action` | The action to take for the command. Possible values:
  • `allow` – Execute automatically without user approval.
  • `ask` – Prompt for user approval before execution.
    •  | +{width="706"} + +Rules are evaluated top to bottom, with the first match taking precedence. Thus, in the following example, `npm install` +will ask for permission, but `npm test` will be allowed automatically: + +```json +{ + "rules": [ + { + "pattern": "npm install *", + "action": "ask" + }, + { + "prefix": "npm", + "action": "allow" + } + ] + } +``` + +### Agent skills + +# Agent skills + + + +Every project has patterns that shouldn't require explaining twice — naming conventions, test structure, deployment +steps, code review rules. Agent skills let you codify these once and Junie follows them automatically whenever +they're relevant. + +Agent skills are folders with instructions, templates, scripts, and reference materials that provide Junie with +task-specific context. Skills follow the open [Agent Skills](https://agentskills.io/specification) +format and are portable across agents. + +Unlike [guidelines](Guidelines-and-memory.md), which are applied with every prompt, agent skills are only invoked when they match +the needs of the current task. Junie follows the skill instructions, loading referenced materials or executing +bundled scripts as needed. + +Skills work in both [Junie CLI](Junie-CLI.md) and [Junie in JetBrains IDEs](Junie-IDE-plugin.md). + +> Junie is included with your [JetBrains AI subscription](https://www.jetbrains.com/ai/). Open your IDE, press +> Shift+Tab, and ask Junie to create a skill for your project. +> {style="tip" title="Try it now"} + +## Why agent skills? + +Think of skills as cheat sheets that Junie consults when working on specific types of tasks to produce better results. +The benefits of agent skills are: + +* **Progressive disclosure**: each skill's name and description are available to Junie, so it knows what skills exist, +but doesn't read the full content of a skill until it determines its relevance to the task. +* **Instructions with attached files**: instructions are bundled with reference materials such as templates or +assets, so Junie has all the context it needs to complete the task. +* **Portability**: if your project already has skill folders from other agents (`.cursor/skills/`, `.claude/skills/`, +or `.codex/skills/`), Junie CLI will detect them and suggest importing into Junie's `.junie/skills/` directory. + +## What you can do with skills + +Here are real examples of what teams build with skills: + +| Skill | What it does | +|-----------------------|---------------------------------------------------------------------------------------------------------| +| API scaffolding | Creates REST endpoints with validation, tests, and OpenAPI docs that follow your project's conventions. | +| Code review | Catches null safety issues, naming violations, and anti-patterns against your team's style guide. | +| Database migration | Generates Flyway or Liquibase scripts that follow your existing migration patterns. | +| Test coverage | Identifies untested paths and generates tests matching your project's existing test style. | +| CI/CD pipeline | Builds GitHub Actions or GitLab CI configs that follow your deployment conventions. | +| Component templates | Scaffolds UI components with your team's file structure, naming, and boilerplate. | +{width="706"} + +Each skill is a folder you can check into version control and share across your team. + + +## How Junie CLI uses skills + +Junie CLI invokes agent skills *automatically*. It scans folders inside `.junie/skills/` at the user and project +levels and selects the skills that are relevant to the current task. + +### Skill location + +Junie CLI looks for skill folders in two locations: + +* **Project scope**: `/.junie/skills//`. + + Skills in this folder are available only in the current + project but can be checked into version control and shared across all team members. + +* **User scope**: `~/.junie/skills//` on macOS/Linux or `%\USERPROFILE%\.junie\skills\\` on Windows. + + Skills in this folder are available globally across all projects on your machine while remaining private to your user account. + +[//]: # (> The default user-level path can be changed by setting the `JUNIE_HOME` environment) +[//]: # (> variable. In that case, skills are loaded from `$JUNIE_HOME/skills/` (macOS/Linux) or `%\JUNIE_HOME%\skills\` (Windows).) + +> If a project-level (`/.junie/skills//`) and a user-level (`~/.junie/skills//`) +> skills share the same name, the project-level skill takes precedence and the user-level skill is ignored. +> {style="note" title="Scope priority"} + +[//]: # (When you add or update skills, Junie CLI notifies you at the start of the next session.) + +### Skill directory structure + +Each skill lives in its own folder under the `.junie/skills` directory: + +``` +.junie/skills/ +├── my-skill/ +│ ├── SKILL.md # Required: Main skill documentation +│ ├── scripts/ # Optional: Executable scripts +│ │ └── setup.sh +│ ├── templates/ # Optional: Code or doc templates +│ │ └── component.kt +│ └── checklists/ # Optional: Detailed checklists +│ └── review.md +├── another-skill/ +│ └── SKILL.md +``` + +- The `SKILL.md` file is **required**. A folder without it is not recognized as a skill. +- Subdirectories are optional and can contain any supporting files (checklists, scripts, templates, etc.) that Junie CLI + can read when needed. + +### `SKILL.md` format + +The `SKILL.md` file uses Markdown with a YAML frontmatter header: + +```Markdown +--- +name: my-skill-name +description: A short description of what this skill provides +--- + +# My Skill Name + +Use this skill when [describe when Junie should use this skill]. + +## Key Principles +- Principle 1 +- Principle 2 + +## Guidelines +- Guideline 1 +- Guideline 2 + +## Examples + +[Include code examples, patterns, or references to project files] + +## Checklist + +See `checklists/review.md` for a detailed checklist. +``` + +#### Frontmatter fields + +| Field | Type | Required | Description | +|---------------|--------|----------|------------------------------------------------------------------------------------------------| +| `name` | String | **Yes** | A unique identifier for the skill. | +| `description` | String | No | A short summary that Junie CLI can use to determine the skill's relevance to the current task. | +{width="706"} + +> If `description` is not provided in the frontmatter, Junie CLI extracts the first paragraph of the body content +> as the description. If the body is also empty or contains only headings, the skill will fail to load. +> For best results, always provide an explicit `description`. Accurate description helps Junie CLI trigger the skill at the right time. +> {style="note" title="Description fallback"} + +#### Body content + +The body (everything after the closing `---`) is the main skill documentation, which should contain actionable +instructions that Junie CLI should follow along with the paths to relevant project files, templates, or additional +materials within the skill folder. + +## Adding a skill + +### Prompt Junie to add a skill + +The easiest way to add a skill is to ask Junie to create it for you. Describe what you want the skill to cover, +and Junie will generate the skill folder, `SKILL.md`, and any supporting files. + + + +**Example prompt:** + +Create a skill that enforces our API design conventions: all REST endpoints must use kebab-case URLs, return JSON +responses wrapped in a `{ data, error }` envelope, and include request validation using our shared `ValidationUtils` +class. Add a checklist for reviewing new endpoints. + + + +You can also create skills on the fly from your current task if the guidelines or patterns Junie followed +could be reused in future tasks. + + + +**Example prompt:** + +The conventions we've been following for database migrations in this task are useful — create a skill from them so we +follow the same approach next time. + + + +### Create your own skill + +1. Create a `.junie/skills/` directory. + +2. Add a skill folder to the `.junie/skills/` directory. + +3. Add a `SKILL.md` file to the skill folder. + +```Markdown +--- +name: my-new-skill +description: Provides guidelines for [specific domain or task] +--- + +# My New Skill + +Use this skill when [describe the trigger conditions]. + +## Key Principles + +- [Actionable principle 1] +- [Actionable principle 2] + +## Guidelines + +- [Specific guideline with examples] +- [Reference to project files: `path/to/relevant/file.kt`] + +## Code Patterns + + ```kotlin + // Example of the preferred pattern + fun example() { + // ... + } + ``` +## Additional Resources + +- See `checklists/my-checklist.md` for a detailed checklist. +- Run `scripts/setup.sh` to configure the environment. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/my-new-skill/SKILL.md"} + +4. (Optional) Add supporting files to the skill folder. + + If your skill needs additional resources, create subdirectories with supporting files. + +5. Verify that the skill loads. + + Ask Junie to list its available skills to confirm it loaded correctly. + +[//]: # (Start a new Junie session. You should see a notification that a new skill was detected.) + +### Add skills from public repositories + +You can import skills shared by the community or your organization by copying them from public Git repositories into +your skills directory. + + + + +```bash +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git /tmp/junie-skills + +# Copy a specific skill to your project +cp -r /tmp/junie-skills/spring-kotlin-code-review .junie/skills/ + +# Or copy to your global skills for use across all projects +cp -r /tmp/junie-skills/spring-kotlin-code-review ~/.junie/skills/ + +# Clean up +rm -rf /tmp/junie-skills +``` + + + + +```powershell +# Clone the repo (or download just the skill folder) +git clone https://github.com/JetBrains/skills.git $env:TEMP\junie-skills + +# Copy a specific skill to your project +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review .junie\skills\ + +# Or copy to your global skills for use across all projects +Copy-Item -Recurse -Force $env:TEMP\junie-skills\spring-kotlin-code-review "$env:USERPROFILE\.junie\skills\" + +# Clean up +Remove-Item -Recurse -Force $env:TEMP\junie-skills +``` + + + +>Junie modifies your code and executes scripts, so it's important to make sure that the skills it uses are safe. +>Treat third-party skills with the same caution as you would with any third-party code you add to your project: +> +>* Only use skills from sources you trust. +>* Read the `SKILL.md` file and all supporting files carefully. +>* Prefer pinning to a specific commit or tag rather than pulling from a branch that may change. +> +{title="Always review skills from external sources before using them" style="warning"} + +## Best practices + +* Be specific and actionable, and provide as many details as possible. + + Avoid vague instructions like *Write good tests*. Instead, prefer: + + ```markdown + Use the AAA pattern (Arrange, Act, Assert). + One assertion concept per test. + Use fakes instead of mocking libraries. + ``` + +* Include examples and show the exact patterns you want Junie to follow. +Skills with code examples are significantly more effective. + +* Reference project files. Point Junie to existing code that exemplifies the desired patterns: + + ```markdown + See `src/test/kotlin/com/example/MyServiceTest.kt` for a reference + test implementation. + ``` + +* Keep it focused. Each skill should cover one domain or concern. Don't create a single monolithic skill that covers +everything – create multiple focused skills instead. + +* Use subdirectories for complex skills. If a skill has extensive documentation, break it into multiple files: + - Main `SKILL.md` provides an overview and links to sub-documents. + - `checklists/` for step-by-step verification lists. + - `scripts/` for automation scripts Junie can execute. + - `templates/` for boilerplate code Junie can use as starting points. + +* Write a clear description. The `description` field is what Junie uses to decide whether a skill is relevant. +Although the field is optional (Junie CLI can extract a description from the body content), providing an explicit +`description` is recommended so Junie can match the skill to the right tasks without ambiguity. + +## Troubleshooting + + + +- Junie selects skills based on task relevance. If a skill isn't being used, it may not match the current task, +or its description may be too vague or generic. Make sure the skill's `description` clearly communicates when it should be used. +- Try asking Junie to use a specific skill explicitly, for example: *Use the testing skill to write tests for this module.* +- Check for name conflicts: if a project-level and a user-level skills have the same name, the user-level skill will be skipped. +- Verify the [SKILL.md file format](#skill-md-format) is followed: proper YAML formatting (no tabs, correct indentation), +the YAML frontmatter starts with `---`, contains at least the `name` field, and ends with `---`; +if `description` is omitted, make sure the body contains at least one paragraph of text so Junie CLI can extract a description. +- Check file permissions and encoding (UTF-8) for file read errors. + + +## Example skill folder + +Below is an example code review skill that contains the main `SKILL.md` file and a referenced checklist. + +``` +.junie/skills/code-review/ +├── SKILL.md +└── checklists/ + └── kotlin.md +``` + +```Markdown +--- +name: code-review +description: Provides guidelines and checklists for thorough Kotlin code reviews +--- + +# Code Review Skill + +Use this skill when reviewing Kotlin code for quality, correctness, and maintainability. + +## Review Priorities + +1. **Correctness**: does the code do what it's supposed to? +2. **Error Handling**: are errors handled gracefully? +3. **Readability**: is the code easy to understand? +4. **Performance**: are there obvious performance issues? +5. **Testing**: are there adequate tests? + +## Kotlin-specific checks + +- Prefer `val` over `var` +- Use data classes for value objects +- Prefer early returns over nested `if` blocks +- Use sealed classes for restricted hierarchies + +## Detailed Checklist + +See `checklists/kotlin.md` for a comprehensive review checklist. +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/SKILL.md"} + +```Markdown +# Kotlin Code Review Checklist + +## Naming +- [ ] Classes use PascalCase +- [ ] Functions and variables use camelCase +- [ ] Constants use SCREAMING_SNAKE_CASE + +## Null Safety +- [ ] Avoid `!!` operator +- [ ] Use `?.let {}` or safe calls +- [ ] Nullable types are justified + +## Error Handling +- [ ] Errors are handled gracefully +- [ ] Error propagation is clean and readable + +## Testing +- [ ] New code has corresponding tests +- [ ] Edge cases are covered +- [ ] Tests follow AAA pattern +``` +{collapsible="true" default-state="collapsed" collapsed-title=".junie/skills/code-review/checklists/kotlin.md"} + +## What's next + +- [Get started with Junie](Get-started-with-Junie.topic) — install Junie and run your first task. +- [Guidelines and memory](Guidelines-and-memory.md) — project-wide rules that apply to every prompt. +- [Junie CLI usage](Junie-CLI.md) — command reference and configuration. +- [Custom LLM models](Custom-LLM-models.md) — use your own models with BYOK. + +### MCP + + + +# Add and configure MCP servers + +You can connect Junie CLI to external tools via Model Context Protocol (MCP). +Junie CLI uses the same MCP JSON configuration as +[Junie in JetBrains IDEs](Junie-IDE-plugin.md#mcp-configuration). + +The `/mcp` slash command shows the [list of configured MCP servers](#list-configured-mcp-servers) and the +[MCP Installation Assistant](#mcp-installation-assistant) to guide you through +adding, editing, or troubleshooting configs for MCP servers. + +[//]: # (TODO: differentiation between inactive and failed statuses is not clear) + +## MCP Installation Assistant + +Junie's MCP Installation Assistant is an AI helper that streamlines and simplifies the process of adding new MCP servers. +It guides you through adding MCP servers from a registry of pre-configured servers or from scratch. + +When adding a server from the registry, Junie CLI automatically configures the correct command or URL and prompts the user for +any required secrets or environment variables. + +When adding a server from scratch, it searches the [official MCP registry](https://registry.modelcontextprotocol.io/) +for the proper server configuration, prompts for parameters, env variables, secrets, or API tokens if needed, adds the server +configuration to the `mcp.json` file, and verifies the server startup. + +![](mcp_installation_assistant.png){width=680} + +### Add an MCP server + +1. Use the `/mcp` command to open the MCP server configuration screen. + +2. Press `Ctrl+A` to open and search the list of pre-configured MCP servers. + + If the MCP server you need is not on the list, press `Ctrl+A` once again and follow Installation Assistant's prompts +to set up the server configuration from scratch. + +3. Select the server installation scope: + + * **Project scope**: MCP server configs are stored in the `.junie/mcp/mcp.json` file at the root of your project. This file + can be checked into version control and shared across all team members. + > For project-scope installations, avoid sharing secrets or sensitive environment variables + > if the `.junie/mcp/mcp.json` file is committed to version control. + > {title="Warning"} + + * **User scope**: user-scope MCP configs are stored in `~/.junie/mcp/mcp.json` and available across all projects + on your machine while remaining private to your user account. + +4. Select the server connection type: + + * **Remote**: connect to a hosted server via HTTP/HTTPS. + + Junie CLI connects to an MCP server hosted on a remote machine or service. + + * **Local**: run on your machine (Docker, npx, or binary). + + Junie CLI starts an MCP server instance locally, e.g. + using the `npx` command or via Docker. + +### OAuth authorization + +Remote MCP servers that require OAuth authorization are added to the list of configured servers with +an **Authorization required** status. Use MCP Installation Assistant to set up OAuth authorization: + +1. Select the server on the list to open its configuration menu. + +2. Select **→ Authorize** and then follow the steps to login in the respective server's browser page that opens. + +3. Verify that the server's status has changed to **Active**. + +## Add an MCP server from JSON configuration + +If you have a JSON configuration for an MCP server, you can add it manually directly to the `.junie/mcp/mcp.json` file +at the project or user scope. + +The `mcp.json` file uses the following JSON structure: + +```json +{ + "mcpServers": { + "Context7": { + "command": "npx", + "args": ["-y", "@upstash/context7-mcp"], + "env": { + "ENV_VAR": "value" + } + }, + "RemoteServer": { + "url": "https://mcp.example.com/v1", + "headers": { + "Authorization": "Bearer token" + } + } + } +} +``` +{collapsible="true" collapsed-title="mcp.json"} + +Manually added configurations are imported to the list of MCP servers and enabled by default. +To verify that the server is available to Junie CLI and active, use the `/mcp` command. + +## List configured MCP servers + +To list all configured MCP servers, as well as disable/enable, modify, +or delete existing configurations, use the `/mcp` command. The list shows: + +* MCP server name. +* Installation scope (project or user). +* Server status (Starting/Active/Inactive/Disabled/Failed/Authorization required). + +> Servers that are neither *Active* nor *Disabled* can be either *Inactive* or *Failed*. +> +> The *Inactive* status indicates that the server is correctly configured and enabled but is not currently running. +> +> The *Failed* status indicates that an error occurred while attempting to connect to the server, +> the server cannot be started or crashes while running. +> This could be due to invalid configuration, authentication failure, missing dependencies, or server's runtime crash. +> {title="MCP server statuses"} + +Configuration for MCP servers is stored in the `mcp.json` file at the following default locations: +* **Project scope**: `.junie/mcp/mcp.json` at the root of your project. +* **User scope**: `~/.junie/mcp/mcp.json` on your machine. + +You can control where Junie searches for MCP configurations using the following command-line options: + +| Option | Default | Description | +|---|---|---| +| `--mcp-default-locations` | `true` | Enable or disable adding MCP servers from default locations (per user / per project). | +| `--mcp-location ` | — | Additional folders where MCP servers should be found. Can be specified multiple times. | + +## Enable or disable an MCP server + +The MCP servers connected via MCP Installation Assistant or imported from the `mcp.json` file are enabled by default. + +To disable a server, list all the configured servers with the `/mcp` command, select the necessary server, +and then select the **→ Disable** action. To enable a previously disabled server, use **→ Enable**. + +### Extensions + + + +# Add and configure extensions + +Extensions are reusable bundles that extend Junie CLI with project-specific or +domain-specific capabilities. A single extension can package any combination of: + +* [Agent skills](Agent-Skills.md) +* [MCP servers](Junie-CLI-MCP-configuration.md) +* [Subagents](Junie-CLI-subagents.md) +* [Custom slash commands](Custom-slash-commands.md) +* [Guidelines](Guidelines-and-memory.md) + +This makes extensions a convenient way to install a curated set of capabilities for a particular +technology stack (for example, an Android, Spring Boot, or SQL extension), share team-wide setups, +or distribute community-built integrations — without manually configuring each piece. + +Run the `/extensions` slash command (aliases: `/plugin`, `/plugins`) to open the +extensions screen, where you can browse marketplaces, install, update and remove +extensions, and configure additional marketplaces. + +## Marketplaces + +Extensions are distributed via marketplaces. A marketplace exposes a manifest with a list of +available extensions and references to where their content is hosted. Junie CLI supports three +ways to host a marketplace: + +* A git repository (GitHub, GitLab, self-hosted, any host). +* A local directory on your machine. +* A direct HTTP(S) URL pointing at a `marketplace.json` file. + +Two manifest formats are supported in all three cases: + +* The native Junie format at `.junie-extension/marketplace.json`. +* The [Claude plugin](https://docs.claude.com/) format at `.claude-plugin/marketplace.json`. + +This means you can connect any Claude-compatible plugin marketplace to Junie CLI in addition to +Junie's native marketplaces. + +### Built-in marketplace + +Junie CLI ships with the official JetBrains marketplace pre-registered: + +[https://github.com/JetBrains/junie-extensions](https://github.com/JetBrains/junie-extensions) + +The marketplace contains a curated set of extensions maintained by the Junie team — +for example, extensions for Java, Kotlin, Android, Spring Boot, SQL, Redis, and others. + +### Add a custom marketplace + +To register an additional marketplace: + +1. Run `/extensions` and switch to the **Marketplaces** tab. +2. Choose **Add marketplace** and provide one of the supported spec formats: + + | Spec | Recognized as | + |------|---------------| + | `https://github.com/owner/repo` | GitHub repository (clones locally) | + | `owner/repo` | GitHub shorthand, expanded to `https://github.com/owner/repo` | + | `git@github.com:owner/repo` | Git over SSH | + | `https://gitlab.com/owner/repo` (or any other host) | Generic git repository | + | `./relative/path`, `/abs/path`, `~/path`, `file:///…` | Local directory | + | `https://example.com/marketplace.json` | Direct URL to a `marketplace.json` (HTTP-only, no clone). GitHub `/blob/` URLs are auto-rewritten to the raw form. | + + The source must contain either a `.junie-extension/marketplace.json` or a + `.claude-plugin/marketplace.json` file at its root (for git / local sources). URL sources + point directly at the manifest file. + +3. Depending on the type, Junie CLI clones the repo, probes the local directory, or fetches the + JSON, then lists its extensions in the catalog. + +To remove a custom marketplace, select it in the **Marketplaces** tab and choose **Remove**. +The built-in JetBrains marketplace cannot be removed. + +You can also drive the same actions inline via `/extensions `: + +```text +/extensions marketplace add +/extensions marketplace remove +``` + +## Install an extension + +1. Run `/extensions` to open the extensions screen. + +2. Browse the catalog of available extensions across all registered marketplaces, or use search + to find a specific extension. + +3. Select an extension and choose the installation scope: + + * **Project scope**: the extension is enabled only in the current project. The reference is stored + in `.junie/extensions.json` at the root of the project. This file can be checked into + version control and shared with the team. + + * **User scope**: the extension is enabled across all projects on your machine. The reference is + stored in `~/.junie/extensions/extensions.json` (or `%\USERPROFILE%\.junie\extensions\extensions.json` on Windows). + +Extension content (skills, agents, commands, MCP configs, guidelines) is downloaded once into +the user-level cache directory `~/.junie/extensions///` and reused across +projects. + +You can also pass a raw trailing argument directly to the `/extensions` command, for example: + +```text +/extensions install +``` + +Newly installed extensions become available within the running session — there is no need to +restart Junie CLI. + +## Remove an extension + +To uninstall an extension: + +1. Run `/extensions` and switch to the **Installed** tab. +2. Select the extension and choose **Remove**. + +The reference is removed from the corresponding `extensions.json` file. Cached content under +`~/.junie/extensions/` may be reused if the extension is reinstalled later. + +## Update an extension + +To pull the latest version of an installed extension, select it in the **Installed** tab and +choose **Update**. + +## Where extensions are stored + +| Location | Purpose | +|-----------------------------------------|--------------------------------------------------------------------------------------------------| +| `~/.junie/extensions/` | Base directory for cached extension content. | +| `~/.junie/extensions/extensions.json` | User-scope configuration: extensions enabled for the current user across all projects. | +| `~/.junie/extensions/marketplaces.json` | Registry for registered marketplace repositories and their sync status. | +| `.junie/extensions.json` | Project-scope configuration: extensions enabled for the current project; can be committed to VCS. | +| `~/.junie/extensions/marketplaces/` | Per-marketplace caches: git clones, local-dir caches, fetched `marketplace.json` files. | + +Both `extensions.json` files share the same format: a flat JSON object that maps a marketplace +identifier to the list of installed extensions for that marketplace. A typed `source` is stored +alongside so a teammate who pulls the project can auto-register the marketplace without +configuring it manually: + +```json +{ + "github-JetBrains-junie-extensions": { "extensions": ["context7"] }, + "github-myorg-myrepo": { + "url": "https://github.com/myorg/myrepo", + "source": { "type": "git", "url": "https://github.com/myorg/myrepo" }, + "extensions": ["my-ext"] + }, + "local-my-dir-abc12345": { + "source": { "type": "local", "path": "/Users/me/my-marketplace" }, + "extensions": ["my-local-ext"] + }, + "url-github-anthropics-knowledge-work-plugins-xxxxxxxxxx": { + "source": { "type": "url", "url": "https://raw.githubusercontent.com/anthropics/knowledge-work-plugins/main/.claude-plugin/marketplace.json" }, + "extensions": ["some-ext"] + } +} +``` + +The legacy `url` field is kept populated for git sources so older Junie versions can still +downgrade-read the config. + +You can override the base directory with the following command-line option: + +| Option | Default | Description | +|----------------------------------------|----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--extensions-default-location ` | `~/.junie/extensions` | Override the default extensions directory. Can also be set via the `JUNIE_EXTENSIONS_DEFAULT_LOCATION` environment variable. | + +### Subagents + +# Custom subagents + + + +Subagents in Junie extend the built-in logic of the main agent with task-specific instructions that define a tailored system +prompt, tool restrictions, and usage of models and [agent skills](Agent-Skills.md). + +When Junie CLI runs across a task that matches a subagent’s name and description, it delegates this task to that subagent. +The subagent then works independently in its own context and returns the result to the main agent. + +This page describes the [benefits of using custom subagents](#why-subagents), +[how custom subagents are invoked](#how-junie-cli-uses-subagents), +[adding your own subagents](#creating-a-custom-subagent) to Junie CLI, and what [built-in tools](#supported-tool-groups) +are supported. + +## Why subagents? + +With subagents, Junie CLI can extend the capabilities to the main agent by delegating tasks to the most appropriate handler +based on the nature of the request. Subagents let you: + +* **Break down complex tasks** into focused, single-purpose chunks that the main agent can delegate +while keeping the subagent's context out of the main conversation. +* **Tailor and reuse agent's behaviour for specific tasks** by defining coding standards, checklists, procedures, or +agent skills to invoke and reusing these instructions across projects. +* **Optimize performance and costs** by using lightweight models for simple repetitive tasks, or predefined models for + specific types of tasks. +* **Enforce tool restrictions** for specific types of tasks, such as restricting the agent to read-only operations +for security auditing and reviews. + +## How Junie CLI uses subagents + +Junie CLI invokes subagents *automatically*, informing the user which subagent has started +working on the task. + +The main agent discovers all available subagents, selects the relevant subagent by matching its [`name` and `description`](#frontmatter-fields) to the task at hand, +runs it as a subtask, and brings the result back into the main session. + +### Configure subagent usage + + + +> This setting is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +Use `/settings` → **Subagents** to choose the subagents model selection policy. The setting is saved in `~/.junie/settings.json` +and applies to new sessions. + +| Mode | Behavior | +|------|----------| +| **SameModelOnly** | Junie CLI may use subagents only for independent work that can run in parallel and reduce elapsed time. Subagents always use the same model as the main agent. | +| **Auto** | Junie CLI may use SameModelOnly-style parallelism and may choose cheaper capable model tiers for suitable delegated work when it does not slow the session. This is the default mode. | + +The **Subagents** setting appears only when subagents are enabled in the current environment. + +> Unlike [custom slash commands](Custom-slash-commands.md), custom subagents cannot be invoked manually +> via slash commands. They are only called automatically through delegation. + +> If your project already has agent files from other tools (`.cursor/agents/`, `.claude/agents/`, or `.codex/agents/`), +> Junie CLI detects such files when opening the project and suggests importing them into Junie's `.junie/agents/` +> directory automatically. +{title="Agent import"} + +## Creating a custom subagent + +Subagents are Markdown files with YAML metadata stored in the `.junie/agents/` or `.agents/` directory. For example, a simple +subagent file for a changelog assistant (`.junie/agents/changelog.md`) looks as follows: + +```yaml +--- +name: "changelog" +description: "Write a changelog entry for a PR" +--- + +You are a changelog assistant. + +Given the PR title and description, produce a short changelog entry. +``` + +### File location + +Junie CLI looks for custom subagent `*.md` files in the following locations: + +* *Project scope:* `/.junie/agents/`. +* *Project scope:* `/.agents/`. +* *User scope:* `~/.junie/agents/` on macOS/Linux or `%\USERPROFILE%\.junie\agents\` on Windows. +* *User scope:* `~/.agents/` on macOS/Linux or `%\USERPROFILE%\.agents\` on Windows. + +### File format + +Subagent files use YAML frontmatter for metadata, followed by the prompt body in Markdown for the system prompt. + +An example subagent file that uses the commonly used supported frontmatter fields looks as follows: + +```markdown +--- +description: "Review a change and propose a safe patch" +name: "code-review-helper" +tools: ["Read", "Grep", "Edit"] +disallowedTools: ["Bash", "WebSearch"] +mcpServers: ["github"] +model: "sonnet" +reasoningLevel: "high" +maxTurns: 20 +skills: ["kotlin", "writerside"] +allowPromptArgument: true +--- + +You are a careful code reviewer. + +Context: + +- File: $path +- Focus area: $focus + +Tasks: + +1) Explain the issue concisely. +2) Propose a minimal fix. +3) If edits are needed, prepare a small patch. + +If you need additional context, ask for it. +``` + +#### Frontmatter fields + +| Field | Type | Required | Notes | +|-------------------|----------------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `name` | `String` | no | The subagent name. If missing, the file name (without extension) is used.

    Must match: `[a-z][a-z0-9-]*` (lowercase letters, digits, hyphens). | +| `description` | `String` | yes | The subagent description. Used by the main agent to decide when to delegate a task to this subagent. | +| `tools` | `List` | no | If present and non-empty: an allowlist of [tool groups](#supported-tool-groups). | +| `disallowedTools` | `List` | no | A denylist of [tool groups](#supported-tool-groups). Applied after the `tools` filtering. | +| `mcpServers` | `List` | no | If present and non-empty: an allowlist of MCP server names. Only tools from the listed servers are exposed to the subagent; all other configured MCP servers are hidden. An empty or omitted list keeps every configured MCP server available. | +| `model` | `String` | no | Default model for this subagent (if supported by your environment). When set, this model is always used for this subagent. Accepted values depend on your environment; to see the model names currently available in your setup, start Junie and use `/model`, or use a name accepted by the `--model` CLI flag. Some builds also support aliases like `sonnet`, `opus`, `grok`, and custom model profile IDs in the `custom:` format. For more details, see [Model selection](Junie-CLI-Model-selection.md). | +| `reasoningLevel` | `String` | no | Optional reasoning override for this subagent run. The `effort` key is accepted as an alias (and takes precedence if both are present). In most cases, use values such as `low`, `medium`, or `high`, but supported values can vary by model, so check the model's own documentation if in doubt. Junie maps the selected level to the provider-specific reasoning field for the effective model, including compatible custom model profiles. | +| `maxTurns` | `Int` | no | Optional cap on the number of steps (turns) the subagent may take before it must finish. Must be a positive integer. When set, it overrides the default step limit for this subagent. | +| `skills` | `List` | no | IDs/names of agent skills to load for the subagent worker (if supported by your environment). | +| `allowPromptArgument` | `Boolean` | no | If `true`, Junie exposes an additional `$prompt` argument to the subagent prompt. When `$prompt` is not referenced explicitly in the prompt body, the delegated user request is appended automatically as `User Input: ...`. | + +#### Prompt body + +In the prompt body, provide the set of instructions to guide the subagent’s behavior. This prompt will be added to the +instructions delegated from the main agent. + +#### Tips + +* Make delegated work items as independent as possible. +* Ask for specific outputs (for example, “return file paths and the exact symbol names”). +* If you want to keep changes small, say so (“no refactors”, “touch at most one module”, “prefer config-only fix”). + +## Supported tool groups + +Custom subagents can define which tool groups are allowed (`tools`) or forbidden (`disallowedTools`) during task execution. + +If the `tools` field in the YAML frontmatter is present and non-empty, **only the specified groups are allowed**, +with the rest being banned by default. There's no need to disallow them explicitly using the `disallowedTools` field. + +There are two types of tools that can be either allowed or banned: + +* **Built-in tool groups**. +* **Tools provided by MCP servers** (if available in your environment). + +The built-in tool group labels are: + +| Built-in tool group label | What it enables | +|---------------------------|---------------------------------------------------------| +| `Read` | Read-only file viewing actions (open/scroll). | +| `Bash` | Running shell commands in the local environment. | +| `Glob` | Searching for files by path pattern (`glob`). | +| `Grep` | Searching for text by regular expression (`grep`). | +| `Write` | Creating new files. | +| `Edit` | Modifying existing files (search/replace, apply patch). | +| `WebSearch` | Searching the web for up-to-date information. | +| `AskUserQuestion` | Asking the user for input or a choice. | + +Example of a read-only subagent allowed to search for a text by regular expression: + +```yaml +--- +name: "symbol-finder" +description: "Find where a symbol is used and summarize" +tools: [ "Read", "Grep" ] +--- +``` + +### Guidelines and memory + +# Guidelines and memory + + + +## Guidelines + +Guidelines allow you to provide persistent, reusable context to the agent. Junie CLI reads guidelines +from the `AGENTS.md` file and adds this context to every task it works on. + +Additionally, Junie CLI checks for any guidelines or memory files from other AI agents when it opens the project +for the first time. If such files are detected, it will suggest importing the instructions into `.junie/AGENTS.md`. + +### AGENTS.md + +[AGENTS.md](https://agents.md/) is an open file format for guiding coding agents. It's a standard Markdown file +with headings, lists, and plain text that the agents can parse to add to the prompt context. + +[//]: # (For user-defined instructions and project context, Junie CLI reads the `.junie/AGENTS.md` file at the root of your project.) + +### How Junie CLI discovers guidelines + +When Junie CLI starts a task, it looks for guidelines in the following order: + +1. `.junie/AGENTS.md` file in the project root. +2. `AGENTS.md` file in the project root. +3. `.junie/guidelines.md` file or `.junie/guidelines/` folder – Junie's legacy format for guidelines (still supported). + +### Global guidelines {id="global-guidelines"} + +In addition to project-level guidelines, Junie CLI also supports **global guidelines** from `~/.junie/AGENTS.md`. +On Windows, the global guidelines path is `%USERPROFILE%\.junie\AGENTS.md`. +This file lets you define personal preferences or organization-wide rules that apply to all your projects +without duplicating them in every repository. + +**How it works:** + +- If only global or only project guidelines exist, Junie uses whichever is available — no extra annotations are added. +- If both global and project guidelines exist, Junie includes both and marks them clearly. + **Project-level guidelines always take precedence** over global ones when they conflict. +- If the global and project guidelines have identical content, Junie automatically deduplicates and uses the content only once. + + + +An `AGENTS.md` file can include project-specific context such as tech stacks, conventions, or rules. +Providing this information helps Junie better understand your environment, avoid incompatible libraries, +and follow your project's specific architectural patterns. + +Below are some examples of what you can include: + +* **Quick-start checklist:** + +```markdown +# A short bullet list of the most critical rules the agent must follow before doing anything + +- [ ] Read this file and `README.md` before acting. +- [ ] Update `CHANGELOG.md` for user-facing changes. +``` + +* **Local development commands**: + +```markdown +# A table or list of project-specific commands for install, lint, test, build, and span dev server + +| Task | Command | +|----------------------|----------------| +| Install dependencies | `pnpm install` | +| Start dev server | `pnpm dev` | +| Run unit tests | `pnpm test` | +``` + +* **Feature development and decision making:** + +```markdown +# Feature development and decision making + +- Make small, targeted changes instead of building for hypothetical future needs. +- If something is unclear, ask before making assumptions. +``` + +* **UI and architecture:** + +```markdown +# UI and architecture guidelines + +- Use existing design system components. +- Avoid inline styles. +- Follow current domain boundaries. +- Prefer extending existing services. +``` + +* **Security and data handling:** + +```markdown +# Security and data handling + +- Never log tokens or sensitive data. +- Sanitize all user input and use existing auth middleware. +``` + +* **Testing and contribution:** + +```markdown +# Testing and contribution + +- Add unit tests for new business logic. +- Keep changes minimal and avoid large refactors in feature tasks. +- Do not rename files without a valid technical reason. +``` + +* **Non-goals for agents:** + +```markdown +# Explicit prohibitions what agents must NOT do + +- Do not bump major versions of core dependencies without a dedicated PR and discussion. +- Do not change database schema without a corresponding migration file. +``` + +For more technology-specific examples of guidelines with explanations, see the +[junie-guidelines](https://github.com/JetBrains/junie-guidelines) catalog. + + + +[//]: # (## Memory) + +[//]: # () +[//]: # (TBD) + +### Custom slash commands + +# Custom slash commands + +Junie CLI supports custom slash commands that you can create to quickly execute frequently used prompts or +repetitive tasks. Custom commands are added to the list of built-in slash commands that is shown when you type `/`. + +[//]: # (![](custom-slash-command.png){width="706"}) + +To create a custom command: + +1. Use `/commands` → `Create New Command` and provide the command name and description. + +2. Select the command scope: + * *Project-specific commands* are stored as Markdown files in the `.junie/commands` folder at your project’s root directory. + You can commit this folder to version control to ensure that all team members can use it. + * *User commands* are stored as Markdown files in the `~/.junie/commands` folder on your machine, making them + available across all projects you open locally. + +3. Enter and save the prompt. + +To view, modify, or delete the added custom commands, use `/commands`. + +### Use arguments in the command prompt + +You can use special keywords `$argumentName` in the prompt text to pass parameter values when invoking +the custom slash command. + +For example, if you create a command named *explain* and set the prompt as `Explain the code in $file and suggest improvements`, +the `/explain` slash command should be used with the `file` argument when invoked as follows: + +``` +/explain file=src/main.kt +``` +Argument values may be either unquoted or quoted with double or single quotes. + +> A custom slash command will only be executed when all arguments from the command template are provided. +> +> Junie CLI shows inline hints for missing arguments. To autocomplete the missing argument name, use `Tab`. + +Custom slash commands do not accept optional prompts as arguments the same way as [some built-in slash commands](Slash-commands.md#optional-text-as-arguments). +Only named arguments defined in the command template are supported. + +### Slash command file format + +Each custom slash command is saved as a separate Markdown file with YAML frontmatter that defines the command metadata. +The file name is taken from the command name. + +For example, a file for the `/explain` command will be named `explain.md` and look as follows: + + +```markdown + +--- + +description: Explains code in a given file + +--- + + +Explain the code in $file and suggest improvements. + +``` + +### Custom proxies + +# Custom proxies + + + +Custom proxies let you route Junie's LLM traffic through a self-hosted or third-party proxy endpoint instead of the default JetBrains AI service. +This is useful when your organization runs its own inference gateway, needs to add custom authentication headers, or wants to use a private Ingrazzio-compatible deployment. + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## About the Ingrazzio proxy {id="about-ingrazzio"} + +Ingrazzio is JetBrains' internal proxy protocol that Junie uses to communicate with LLM providers. +The production Ingrazzio endpoint is `https://ingrazzio-cloud-prod.labs.jb.gg`. + +When Junie connects through an Ingrazzio proxy, it uses the base URL to access several sub-endpoints: + +- **LLM chat** — the base path handles streaming chat completion requests. +- **Web search** — the `/search` path provides web search capabilities. +- **URL extraction** — the `/extract` path fetches and extracts content from URLs. +- **Authentication** — the `/auth/test` and `/auth/reset` paths validate the token and license state. + +When using the default JetBrains provider, Junie authenticates automatically via JetBrains Account (JBA). +When using a custom proxy, JBA authentication is bypassed — you must supply any required credentials (such as `Authorization: Bearer `) through the proxy's `headers` field. +All the sub-endpoints above, including authentication, are routed through the selected proxy with those headers. + +## Configure a proxy + +Add a `proxies` array to your `config.json`. Each entry describes a named proxy endpoint: + +```json +{ + "proxies": [ + { + "name": "my-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ] +} +``` + +### Proxy fields + +| Field | Required | Description | +|---|---|---| +| `name` | Yes | A unique name for this proxy. Used to reference it from the `provider` field. | +| `kind` | No | The proxy protocol type. Defaults to `Ingrazzio` if omitted. See [Supported proxy kinds](#supported-proxy-kinds). | +| `api-url` | Yes | The base URL of the proxy endpoint. | +| `headers` | No | A list of extra HTTP headers to send with every request. Each entry uses the format `Header-Name: Header-Value`. | + +## Select a proxy as the active provider + +To make Junie use a configured proxy, set the `provider` field to the proxy name: + +```json +{ + "proxies": [ + { + "name": "corp-proxy", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-proxy", + "model": "sonnet" +} +``` + +You can also override the provider at runtime with the `--provider` CLI flag: + +```bash +junie --provider corp-proxy +``` + +When a proxy is selected as the provider, Junie does **not** use JetBrains AI authentication. +All authentication must be handled through the `headers` you configure on the proxy entry. + +## Legacy: the INGRAZZIO_URL environment variable {id="ingrazzio-url-env"} + +> `INGRAZZIO_URL` is a legacy compatibility mechanism (kept for existing AIR deployments) and will +> eventually be removed. Declare an `Ingrazzio` proxy in `config.json` instead. + +Setting the `INGRAZZIO_URL` environment variable creates an implicit `Ingrazzio`-kind proxy named `ingrazzio-env` pointing at that URL — no `config.json` entry is required: + +```bash +INGRAZZIO_URL="http://127.0.0.1:53367" junie +``` + +The synthetic proxy behaves like a proxy declared in `config.json`: + +* All requests — LLM chat, web search, URL extraction, and authentication (`/auth/test`, `/auth/reset`) — are routed through the given URL, and it appears in the model selector next to configured proxies. +* It automatically becomes the default provider unless another `provider` is selected via the CLI (`--provider`) or `config.json`. +* If `config.json` declares any `Ingrazzio`-kind proxy, that configuration takes precedence and `INGRAZZIO_URL` is ignored entirely. +* If an ingrazzio token is supplied via the environment (for example, `JUNIE_API_KEY` or `EJ_AUTH_INGRAZZIO_TOKEN`), it is sent as the `Authorization` header of the proxy's requests; otherwise Junie falls back to the JetBrains Account token. + +## Supported proxy kinds {id="supported-proxy-kinds"} + +The `kind` field determines which protocol Junie uses to communicate with the proxy. + +| Kind | Status | Description | +|---|---|---| +| `Ingrazzio` | **Supported** | Junie's native proxy protocol. Compatible with JetBrains Ingrazzio deployments. This is the default when `kind` is omitted. | +| `Bedrock` | **Supported** | Anthropic models served through an AWS Bedrock-compatible gateway. Requires the additional Bedrock fields described below. | +| `OpenAI` | Planned | OpenAI-compatible API. | +| `Anthropic` | Planned | Anthropic-compatible API. | +| `JetBrainsAI` | Planned | JetBrains AI Gateway. | +| `OpenRouter` | Planned | OpenRouter-compatible API. | + +## Bedrock proxies {id="bedrock-proxies"} + +A `Bedrock` proxy routes Anthropic models through an AWS Bedrock-compatible gateway. Requests are sent to +`/model//invoke`, where `` is the provider-side model id with Bedrock's default +cross-region inference prefix. + +Because Bedrock model ids differ from Junie's model ids, a Bedrock proxy needs one extra field beyond the common ones: + +| Field | Required | Description | +|---|---|---| +| `available-models` | Yes | JetBrains model ids this proxy exposes (for example, `anthropic-claude-4-6-sonnet`). At least one is required. | + +If the proxy's `headers` include an `Authorization` header, it is used as-is; otherwise Junie falls back to the JetBrains Account token. + +```json +{ + "proxies": [ + { + "name": "corp-bedrock", + "kind": "Bedrock", + "api-url": "https://bedrock-gateway.example", + "available-models": ["anthropic-claude-4-6-sonnet", "anthropic-claude-4-8-opus"], + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "corp-bedrock", + "model": "sonnet" +} +``` + +> The `Ingrazzio` and `Bedrock` kinds are functional. The remaining kinds are reserved for future use and will result in an error at startup. + +## Quick setup example + +1. Create a configuration file (for example, `my-config.json`): + +```json +{ + "proxies": [ + { + "name": "my-ing", + "kind": "Ingrazzio", + "api-url": "https://ingrazzio-cloud-prod.labs.jb.gg", + "headers": [ + "Authorization: Bearer " + ] + } + ], + "provider": "my-ing", + "model": "opus" +} +``` + +2. Run Junie with the custom config: + +```bash +junie --config-location="/path/to/my-config.json" +``` + +You can still override the model at runtime with the `--model` flag: + +```bash +junie --config-location="/path/to/my-config.json" --model sonnet +``` + +## Merging proxies across configuration files + +When multiple configuration files define proxies, they are merged by name: + +* If two files define a proxy with the same `name`, the higher-priority file's fields override the lower-priority file's fields on a per-field basis. +* Headers from both files are combined (deduplicated). +* Proxies with different names are all included in the final list. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* Only the `Ingrazzio` and `Bedrock` proxy kinds are currently supported. Other kinds are reserved for future use. +* Proxy configuration is only available through `config.json`. There are no dedicated CLI flags for defining proxy entries. +* When using a proxy provider, JetBrains AI authentication is bypassed entirely. You must supply any required credentials via the `headers` field. + +### Custom LLMs + +# Custom LLMs + +Junie CLI supports custom models defined via JSON profiles. This feature allows you to integrate with local providers +(e.g., Ollama), enterprise proxies, or any LLM endpoint that follows the supported API formats. + +## Choosing a capable model {id="choosing-a-capable-model"} + +Junie is an agentic tool: it drives a task by calling tools, following multi-step instructions, and reasoning over a +large context (your prompt, file contents, tool output, and the running plan). This places much higher demands on a +model than a plain chat completion. + +Smaller or heavily quantized models often cannot keep up. With a weak model you may see Junie: + +- ignore or partially follow instructions, or drift away from the task; +- emit malformed or incomplete tool calls, so edits and commands fail; +- loop, repeat itself, or stop before the task is finished; +- lose track of earlier steps once the context grows. + +> This is a limitation of the underlying model, not a defect in Junie. The same setup with a more capable model +> typically resolves it. +> +> For agentic use, prefer models with strong instruction following and reliable tool/function calling, a coding-oriented +> training focus, and a large context window. Very small or aggressively quantized variants are best kept for the +> `fasterModel` role (summarization, classification) rather than as the `primaryModel`. +> +> {style="note"} + +## Configuration + +### Location and discovery + +By default, custom models are discovered from JSON files located in: +- User-scope: `$JUNIE_HOME/models/*.json`. +- Project-scope: `.junie/models/*.json`. + +The filename (without the `.json` extension) is used as the **profile identifier**. + +You can control where Junie searches for custom models using the following command-line options: + +| Option | Default | Description | +|-----------------------------|---------|------------------------------------------------------------------------------------------| +| `--model-default-locations` | `true` | Enable or disable adding custom models from default locations (per user / per project). | +| `--model-location ` | — | Additional folders where custom models should be found. Can be specified multiple times. | +{width="800"} + +You can also set these values in the `config.json` file. For details, see [Junie CLI configuration files](Junie-CLI-configuration.md). + +### Profile structure + +A custom model profile consists of a top-level configuration and two optional model roles: + +1. **Top-level properties**: Serve as the default configuration (base URL, API key, API type, and extra headers) for the models in the profile. +2. **`primaryModel`**: The model used for main reasoning and code generation tasks. +3. **`fasterModel`**: The model used for internal helper tasks like summarizing context or classifying tasks. + +If `primaryModel` or `fasterModel` is not explicitly defined, they inherit the top-level properties. + +### Top-level parameters + +These parameters appear at the root of the JSON profile and define the defaults shared by both model roles. + +| Parameter | Type | Required | Description | +|----------------|--------|----------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `id` | String | Yes | The model identifier as expected by the API endpoint (for example, `gpt-4o` or `qwen3-coder:latest`). | +| `baseUrl` | String | Yes | The full URL of the LLM API endpoint (for example, `http://localhost:11434/v1/responses`). | +| `apiType` | String | Yes | The API format to use when communicating with the endpoint. See [Supported API types](#supported-api-types) for the list of accepted values. | +| `apiKey` | String | No | The API key for authenticating with the endpoint. If omitted, requests are sent without an `Authorization` header. Supports [environment variable references](#environment-variables). | +| `extraHeaders` | Object | No | A key-value map of additional HTTP headers to include in every request to the endpoint. Values support [environment variable references](#environment-variables). | +| `extraBody` | Object | No | A JSON object merged into the body of every request to the endpoint. See [Extra body](#extra-body). | +| `temperature` | Number | No | The sampling temperature to use for requests. If omitted, the provider's default temperature is used. See [Temperature](#temperature). | +| `maxContextLength` | Integer | No | The maximum context length supported by the model, in tokens. | +| `primaryModel` | Object | No | Role-specific overrides for the primary model. See [Role-specific parameters](#role-specific-parameters). | +| `fasterModel` | Object | No | Role-specific overrides for the faster model. See [Role-specific parameters](#role-specific-parameters). | + +### Role-specific parameters + +`primaryModel` and `fasterModel` accept the same set of parameters. Any parameter specified here overrides the corresponding top-level value for that model role. Omitted parameters fall back to the top-level defaults. + +| Parameter | Type | Description | +|---|---|---| +| `id` | String | Override for the model identifier used for this role. | +| `baseUrl` | String | Override for the API endpoint URL used for this role. | +| `apiType` | String | Override for the API format used for this role. | +| `apiKey` | String | Override for the API key used for this role. | +| `extraHeaders` | Object | Additional headers for this role. Merged with (not replaced by) the top-level `extraHeaders`. | +| `extraBody` | Object | Additional request body fields for this role. Merged with (not replaced by) the top-level `extraBody`. | +| `temperature` | Number | Override for the sampling temperature used for this role. | +| `maxContextLength` | Integer | Override for the maximum context length supported by this role, in tokens. | + +### Merging logic + +Overrides in `primaryModel` or `fasterModel` are merged with the top-level defaults: +- **Simple fields** (`id`, `baseUrl`, `apiKey`, `apiType`, `temperature`, `maxContextLength`) are replaced by the override value when present. +- **Headers** (`extraHeaders`) are merged: headers defined in the override are added to the top-level headers. If the same header key appears in both, the role-level value takes precedence. +- **Body fields** (`extraBody`) are merged recursively: entries defined in the override are added to the top-level `extraBody`. If the same key appears in both and both values are nested objects, those objects are merged recursively (rather than the override replacing the whole subtree). For any other conflicting value, the role-level value takes precedence. + +### Environment variables {id="environment-variables"} + +Custom model profiles are often committed to a project repository and shared with a team (for example, to share a +custom `baseUrl` or model routing). To avoid leaking secrets, you can reference environment variables inside the +`apiKey` field and inside `extraHeaders` values instead of hardcoding them. + +Use the `${VAR_NAME}` syntax. Junie resolves each reference against the corresponding environment variable when it +loads the profile: + +```json +{ + "baseUrl": "https://openrouter.ai/api/v1/chat/completions", + "id": "your-model", + "apiType": "OpenAICompletion", + "apiKey": "${OPENROUTER_API_KEY}", + "extraHeaders": { + "X-Custom-Auth": "${CUSTOM_AUTH_TOKEN}" + } +} +``` + +A reference must match `${NAME}`, where `NAME` starts with a letter or underscore and contains only letters, digits, +and underscores. Values without any `${...}` reference are used as-is, so existing literal keys keep working unchanged. + +If a referenced environment variable is not set, the profile fails to load and Junie reports an error identifying +the missing variable. Set the variable before starting Junie (or replace the reference with a literal value) to +resolve it. + +### Supported API types {id="supported-api-types"} + +The `apiType` field controls which request format Junie uses when calling the endpoint. + +| Value | Description | +|---|---| +| `OpenAICompletion` | OpenAI Chat Completions API (`/v1/chat/completions`). Compatible with most self-hosted and third-party OpenAI-compatible endpoints. | +| `OpenAIResponses` | OpenAI Responses API (`/v1/responses`). Use this for endpoints that implement the newer Responses API format. | +| `Google` | Google Gemini API format. Use this for Google AI Studio or Vertex AI endpoints. | +| `Anthropic` | Anthropic Messages API format. Use this for Anthropic Claude endpoints. | + +## Extra body {id="extra-body"} + +Some providers and proxies accept additional, non-standard fields in the request body — for example, routing +metadata or tags. Use the `extraBody` parameter to merge a JSON object into the body of every request Junie sends to +the endpoint. + +You can set `extraBody` at the top level (shared by both model roles) or override it per role. A common use case is +tagging requests for a proxy such as LiteLLM: + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-proxy-model", + "apiType": "OpenAICompletion", + "extraBody": { + "tags": ["user:alice", "department:engineering"] + } +} +``` + +The `extraBody` entries are merged into the top level of the request JSON. If a key conflicts with a field Junie +already sets (for example, `model` or `messages`), the `extraBody` value takes precedence, so use it with care. + +## Temperature {id="temperature"} + +By default, Junie does not send a temperature value for custom models, allowing the provider to use its own default. +You can set a specific temperature at the top level (shared by both model roles) or override it per role. + +Recommended temperature values vary by model. For example: + +| Model | Recommended temperature | +|---|---| +| DeepSeek | 0 | +| Gemini | 1 | +| Kimi | 0.6–1 | +| GLM | 0.7 | +| Qwen | 0.6 | +| MiMo | 0.3 | + +> Consult your model provider's documentation for the optimal temperature value. +> Setting temperature to 0 may cause looping behavior with some models. + +## Example profiles + +### Basic profile + +Below is an example of a profile named `local-ollama.json`: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "extraHeaders": { + "X-Custom-Source": "Junie" + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model will be `qwen3-coder:latest`, and the faster model will be `qwen2.5-coder:1.5b`. Both will use the same base URL, API type, and extra headers. + +> The `baseUrl` is used as the complete endpoint URL — Junie does not append a path to it. Set it to the full endpoint +> for your chosen `apiType` (for example, `/v1/chat/completions` for `OpenAICompletion`). + +### Profile with temperature + +Below is an example that sets a default temperature and overrides it for the primary model: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "temperature": 0.6, + "primaryModel": { + "id": "qwen3-coder:latest", + "temperature": 0.3 + }, + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +In this example, the primary model uses temperature `0.3` (overridden), while the faster model inherits the top-level temperature `0.6`. + +## Using custom models + +Once a profile is created, you can select it using the `/model` command or the `--model` flag. Custom models are identified by a `custom:` prefix followed by the profile ID: + +```bash +junie --model custom:local-ollama +``` + +In the interactive TUI, custom models appear in the model selection list after the built-in providers. + +## Provider guides + +For common local and proxy providers, you can connect interactively (no JSON profile required) and let Junie discover +the available models. The following guides cover both the interactive setup and a manual profile: + +- [Ollama](Custom-LLM-Ollama.md) +- [LM Studio](Custom-LLM-LM-Studio.md) +- [LiteLLM](Custom-LLM-LiteLLM.md) + +### Ollama + +# Ollama + +[Ollama](https://ollama.com) runs open-weight models locally and exposes an OpenAI-compatible API. +Junie CLI can connect to a local Ollama server, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- Ollama installed and running. By default it listens on `http://localhost:11434`. +- At least one model pulled locally, for example: + + ```sh + ollama pull qwen3-coder:latest + ``` + +## Connect Ollama (recommended) + +The simplest way to use Ollama is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **Ollama**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:11434`. + + > Enter the server's base URL (host and port only), for example `http://localhost:11434`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered Ollama model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — a non-default API type, extra headers, a per-role `fasterModel`, or a custom temperature — +define a [custom model profile](Custom-LLM-models.md) instead. For a manual Ollama profile, use the OpenAI Chat +Completions endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:11434/v1/chat/completions", + "id": "qwen3-coder:latest", + "apiType": "OpenAICompletion", + "fasterModel": { + "id": "qwen2.5-coder:1.5b" + } +} +``` + +> Ollama implements the OpenAI **Chat Completions** API, not the Responses API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LM Studio + +# LM Studio + +[LM Studio](https://lmstudio.ai) is a desktop app for running local models that exposes an OpenAI-compatible server. +Junie CLI can connect to it, automatically discover the loaded models, and make them available in the model picker. + +## Prerequisites + +- LM Studio installed, with at least one model downloaded. +- The local server started (**Developer** tab → **Start Server**). By default it listens on `http://localhost:1234`. + +## Connect LM Studio (recommended) + +The simplest way to use LM Studio is to point Junie at the server and let it discover the available models — no JSON +profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LM Studio**. +4. Confirm or edit the **Base URL**. The default is `http://localhost:1234`. + + > Enter the server's base URL (host and port only), for example `http://localhost:1234`. Junie probes + > `/v1/models` to discover models and sends requests to `/v1/chat/completions`. Do not append a + > path yourself. + +Junie probes the endpoint and adds every discovered model to the picker. + +## Select a model + +Run `/model` and pick a discovered LM Studio model from the list. Discovered local models appear after the built-in +providers. + +> Local models vary widely in capability. Small or heavily quantized models may struggle with Junie's agentic workflow +> (tool calls, multi-step instructions, long context). See [Choosing a capable model](Custom-LLM-models.md#choosing-a-capable-model). +> +> {style="note"} + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LM Studio profile, use the OpenAI Chat Completions +endpoint and set `baseUrl` to the full path: + +```json +{ + "baseUrl": "http://localhost:1234/v1/chat/completions", + "id": "qwen/qwen3-coder-30b", + "apiType": "OpenAICompletion" +} +``` + +> LM Studio implements the OpenAI **Chat Completions** API. Use `apiType: "OpenAICompletion"`. +> Unlike the interactive flow, a JSON profile's `baseUrl` is the full endpoint URL, so include `/v1/chat/completions`. + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### LiteLLM + +# LiteLLM + +[LiteLLM](https://docs.litellm.ai) is a proxy server that exposes 100+ LLM providers behind a single OpenAI-compatible +API. Junie CLI can connect to a LiteLLM proxy, automatically discover the models it serves, and make them available in +the model picker. + +## Prerequisites + +- A running LiteLLM proxy. By default it listens on `http://localhost:4000`. +- The proxy API key, if your proxy enforces authentication (LiteLLM keys typically start with `sk-`). Optional for + self-hosted proxies that do not require authentication. + +## Connect LiteLLM (recommended) + +Connect interactively and let Junie discover the available models — no JSON profile required. + +1. In an active Junie session, run the `/account` command (or select **Use external LLM providers** on the welcome + screen). +2. Open **Custom models and endpoints**. +3. Select **LiteLLM proxy**. +4. **Step 1 — LiteLLM URL.** Enter the proxy base URL. The default is `http://localhost:4000`. +5. **Step 2 — API key.** Paste your LiteLLM API key, or leave it blank if the proxy does not require one. + +Junie probes the proxy and adds every discovered model to the picker. + +## Connect LiteLLM from the command line + +You can configure the proxy non-interactively with CLI flags or environment variables — useful for CI or scripted +setups: + +| Flag | Environment variable | Description | +|---|---|---| +| `--litellm-url` | `JUNIE_LITELLM_URL` | LiteLLM proxy base URL (for example, `http://localhost:4000`). | +| `--litellm-api-key` | `JUNIE_LITELLM_API_KEY` | LiteLLM proxy API key. Optional for proxies that do not require authentication. | + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 +``` + +These flags connect the proxy and make its models available, but they do not change the active model on their own. +Select a LiteLLM model with `/model` after startup, or set it directly with `--model`: + +```sh +junie --litellm-url http://localhost:4000 --litellm-api-key sk-1234 --model my-coder-model +``` + +## Select a model + +Run `/model` and pick a discovered model from the list. + +## Advanced: define a profile manually + +If you need full control — extra headers, a per-role `fasterModel`, or a custom temperature — define a +[custom model profile](Custom-LLM-models.md) instead. For a manual LiteLLM profile, target the proxy's OpenAI Chat +Completions route and set `baseUrl` to the full path. The `id` is the `model_name` defined in your LiteLLM +configuration, and the master key is passed via `apiKey` (sent as `Authorization: Bearer `): + +```json +{ + "baseUrl": "http://localhost:4000/v1/chat/completions", + "id": "my-coder-model", + "apiType": "OpenAICompletion", + "apiKey": "sk-1234" +} +``` + +For the full profile schema, see [Custom LLMs](Custom-LLM-models.md). + +### Hooks + +# Hooks + + + +Hooks let you run shell commands automatically at well-defined points in a Junie CLI session. +Use them to launch a local proxy and refresh credentials at the start (`SessionStart`), validate or enrich a prompt before it is sent (`UserPromptSubmit`), inspect or block a tool call before it runs (`PreToolUse`), gate task completion behind tests or other checks (`Stop`), alert / page / clean up when the agent loop ends due to an LLM/API error (`StopFailure`), or to flush logs and clean up resources when a session ends (`SessionEnd`), or automatically allow or deny sensitive action permission requests without manual confirmation (`PermissionRequest`). + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +## Configure a hook + +Add a `hooks` object to your user `~/.junie/config.json` or to a file passed with `--config-location`: + +```json +{ + "hooks": { + "SessionStart": [ + { + "matcher": "startup", + "hooks": [ + { + "type": "command", + "command": "aws sso login --profile dev", + "timeout": 30 + } + ] + } + ], + "UserPromptSubmit": [ + { + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-prompt.sh" + } + ] + } + ], + "PreToolUse": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/hooks/check-bash-command.sh" + } + ] + } + ], + "SessionEnd": [ + { + "matcher": "prompt_input_exit|logout", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/flush-session-logs.sh" + } + ] + } + ], + "PermissionRequest": [ + { + "matcher": "Bash", + "hooks": [ + { + "type": "command", + "command": "~/.junie/scripts/check-bash-permission.sh" + } + ] + } + ] + } +} +``` + +Each entry has a `matcher` and a list of `hooks` to run when the matcher matches. + +Project-local hooks from `/.junie/config.json` are ignored by default for safety. +Project configuration is repository-controlled, so Junie will not run shell commands from it automatically. +If you intentionally want to run hooks from a project file, pass that file explicitly with `--config-location`. + +### Matcher entry fields + +| Field | Required | Description | +|---|---|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `matcher` | No | A regular expression matched against the event-specific value: the source for `SessionStart` (e.g. `startup`, `resume`, `clear`, `compact`), the reason for `SessionEnd` (e.g. `prompt_input_exit`, `other`, `logout`), , or the tool name for `PermissionRequest` (e.g. `Bash`, `Edit`, `Read`), or the tool name for `PreToolUse` (e.g. `Bash`, `Write`, `Read`), or the `error` for `StopFailure` (see the [StopFailure](#stopfailure) section for the full 9-value list, e.g. `rate_limit`, `server_error`, `model_refused`). `UserPromptSubmit` and `Stop` do not support matchers — entries always run on every event. If omitted, the entry runs for every value. A configured matcher must match at least one supported value. | +| `hooks` | Yes | A list of hook commands to run when the matcher matches. | + +### Hook command fields + +| Field | Required | Description | +|---|---|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `type` | Yes | The hook type. Only `command` is currently supported. | +| `command` | Yes | The shell command to run. Executed via `sh -c` on macOS/Linux and `cmd /c` on Windows. | +| `timeout` | No | Maximum execution time in seconds for a single command. Defaults to 10 for `SessionStart`, `UserPromptSubmit`, and `PermissionRequest`; 600 for `Stop`, 60 for `StopFailure`, and 2 for `SessionEnd`. Note: for `SessionEnd`, the *total* dispatch budget across all matched entries is capped at 10 seconds; for `StopFailure` it is capped at 60 seconds. A per-command `timeout` larger than this remaining budget is effectively bounded by the overall budget. | +| `blockOnError` | No | `Stop` hooks only. When `true`, any non-zero exit code (other than the already-blocking `2`) is promoted to a block-with-retry, with the command's stdout+stderr fed back to the agent as the block reason. Defaults to `false`. Ignored for other events. | +| `async` | No | When `true`, the hook runs in the background and cannot block or affect the triggering action. `systemMessage` is shown to the user only; `additionalContext` is queued and prepended to the agent prompt on the next user submit; `decision` / `permissionDecision` / `continue` are logged and ignored. See [Run hooks in the background](#run-hooks-in-the-background). Defaults to `false`. | + +## Triggering events + +### SessionStart + +Junie fires `SessionStart` once per session with one of the following sources: + +| Source | When | +|---|---| +| `startup` | A fresh CLI session starts. | +| `resume` | An existing session is resumed within the same CLI process. | +| `clear` | A new session is started inside the same CLI process (for example, via the `/new` command). | +| `compact` | The agent triggers history compaction inside a running task (the SessionStart hook is dispatched on the synthetic compaction session). | + +### UserPromptSubmit + +Junie fires `UserPromptSubmit` every time the user submits a prompt in the interactive TUI, before the prompt is sent to the model. Hooks may add context, log the prompt, or block the prompt entirely. + +Unlike `SessionStart` and `SessionEnd`, `UserPromptSubmit` has no source/reason, so it does not support a `matcher` — every configured entry runs on every prompt. + +### PreToolUse + +Junie fires `PreToolUse` before each tool call, after the action request is parsed but before the tool executes. +The hook can inspect or modify the tool input, add context for the model, request user confirmation, or block the tool entirely. + +The `matcher` is matched against the **tool name** as seen by the model (e.g. `Bash`, `Write`, `Read`, `Edit`, `Glob`, `Grep`). +Omitting the matcher runs the hook for every tool call. + +#### Hook output for PreToolUse + +A `PreToolUse` hook may return a JSON object on standard output to influence what happens next: + +```json +{ + "decision": "allow", + "reason": "human-readable reason shown to the user on block or ask", + "updatedInput": { "command": "ls -la" }, + "additionalContext": "text added to the model context window" +} +``` + +Supported decisions: + +| Decision | Effect | +|---|---| +| `allow` (or omitted) | The tool runs with its original (or updated) input. | +| `ask` | Junie pauses and asks the user to confirm before the tool runs. `reason` and `updatedInput` are forwarded to the confirmation prompt. | +| `block` or `deny` | The tool is not executed. The model receives an error message with the `reason`. | + +If the hook exits with code `2`, the tool is blocked regardless of any output. +Other non-zero exit codes are logged as a warning and the tool proceeds normally. + +`updatedInput` replaces the tool's input with the provided JSON object. +`additionalContext` injects additional text into the model context for that turn. +If the hook output is not valid JSON, the raw stdout is treated as `additionalContext`. + +### Stop + +Junie fires `Stop` synchronously right before the agent transitions a task to a successful submission, so a hook can let it proceed, block the submission with a textual reason that is fed back to the agent as context (causing a retry), or hard-halt the task. + +Stop hooks do not run for chat-type tasks. They are enforced uniformly in both interactive and batch (`-p` / non-interactive) modes; the per-task block cap (see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)) is the only safeguard against runaway loops. + +Stop does not support `matcher` — every configured entry runs on every transition. + +### PermissionRequest + +Junie fires `PermissionRequest` whenever it is about to show a permission dialog asking the user to approve a sensitive action. Hooks can suppress the dialog by automatically allowing or denying the action. + +The matcher is evaluated against the **tool name** for the action: + +| Tool name | Actions | +|---|---| +| `Bash` | Terminal commands, run tests, run app, preview, build, clear app data | +| `Edit` | Editing files (build scripts, config files, general file modifications) | +| `Read` | Reading files outside the project or secret files | +| MCP tool name | MCP tool calls (matched against the tool name, e.g. `github`) | + +A hook that exits successfully (exit code 0) without a blocking decision **automatically approves** the action — the permission dialog is skipped. +A hook that blocks (exit code 2 or `decision: "block"` / `decision: "deny"` in stdout) **automatically denies** the action. +If no hook matches, or a hook fails with a non-zero exit (other than 2), Junie falls back to showing the normal permission dialog (with a warning notification if the hook failed). + +`PermissionRequest` supports matchers — use them to scope hooks to specific tools. + +### StopFailure + +Junie fires `StopFailure` once per agent turn when the LLM/API call backing that turn ends in a documented failure (rate limit, billing error, authentication failure, model refusal, etc.). Use it to send alerts, page on-call, log the event, or run cleanup scripts. + +`StopFailure` is **observability-only**: it has no decision control. Output and exit code from the hook process are ignored — `decision: block` and `continue: false` are demoted to TUI failure notifications and **cannot** retry or abort the agent (which is already exiting). Stdin carries `hook_event_name`, `error` (the matcher target), and `error_details` (the underlying failure description); the field names follow Claude Code's `StopFailure` wire protocol so a Claude-style hook script can be reused. + +Catch-all LLM failure wrappers map to `unknown`. Tool-execution failures, project pre-flight / shell-setup failures, and user-cancellations do **not** trigger `StopFailure`; tool errors will be covered by a future `PostToolUseFailure` hook. The catch-all `unknown` bucket also covers internal `UnexpectedException` wrappers, so it is possible (though rare) for a Junie-side bug — not a real provider failure — to fire `StopFailure` with `error=unknown`; alerting rules that page on `unknown` should account for this. + +Dispatch is non-blocking only in the interactive TUI host: there `StopFailure` is fire-and-forget — the agent surfaces the failure to the user immediately and the hook (bounded by the 60s overall budget) runs in the background. In the batch (`-p` / non-interactive) and server hosts the agent is already exiting, so there is no scope to launch into; the hook runs **synchronously** and the process waits up to 60s for it to finish (or be killed by `withTimeoutOrNull`) before the failing exception is re-thrown. Long-running on-call / paging hooks must therefore not exceed this budget if you rely on them completing before the batch process exits. + +`StopFailure` is matched against the `error` wire value. The 9 values are: + +| `error` | When | +|---|---| +| `rate_limit` | The provider returned a rate-limit error (typically HTTP 429). | +| `authentication_failed` | The provider rejected the API key or token (typically HTTP 401). | +| `billing_error` | The account billing state prevents the call (payment required, cost cap hit, etc.). | +| `invalid_request` | The provider rejected our request shape (malformed JSON, unsupported parameter, …). | +| `server_error` | The provider returned a 5xx, timed out, or the connection was dropped. | +| `max_output_tokens` | The model hit its output token / context limit. | +| `unknown` | An LLM-side failure that did not match any of the above. | +| `model_refused` | The model declined to complete the request (safety mechanisms). Junie-specific. | +| `country_forbidden` | The provider refused the call because of the caller's country. Junie-specific. | + +A `matcher` like `"rate_limit"` runs only on rate-limit failures; `"rate_limit|server_error|model_refused"` runs on all three; omitting `matcher` runs on every error type. + +### SessionEnd + +Junie fires `SessionEnd` whenever a session terminates, with one of the following reasons: + +| Reason | When | +|---|---| +| `prompt_input_exit` | The interactive TUI is exiting (user pressed Ctrl+C, `/exit`, or `/quit`). | +| `other` | A batch (`-p`) or non-interactive task finishes. | +| `logout` | The user explicitly signs out from the TUI account screen ("Sign out"). The hook is dispatched in the background when sign-out is requested and does not block navigation — it may run concurrently with credential clearing, and any failure notifications surface after the fact. | + +> In the interactive TUI, switching away from a session — via `/new`, a `/history` selection, or any other session switch — does **not** end the outgoing session: it continues running in the background and its `SessionEnd` hook is **not** fired on the switch. `SessionEnd` is dispatched only when the session actually terminates (`prompt_input_exit`, `logout`, or `other` for batch). The `clear` and `resume` reasons are reserved in the `SessionEndHookReason` enum but are not currently dispatched in any host. + +Hooks are currently triggered from the interactive TUI host (`SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`, `PermissionRequest`) and the batch host (`SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `SessionEnd`). ACP and server hosts do not yet invoke any hooks; that integration is tracked separately. + +You can scope a hook to a specific source or reason using `matcher`. For example, `"matcher": "startup"` runs the hook only on a fresh start, while `"matcher": "startup\|resume"` runs it on both. Omitting `matcher` is equivalent to matching every value. + +## Hook input + +Each hook receives a single line of JSON on standard input: + +```json +{"hook_event_name":"SessionStart","source":"startup"} +``` + +For `UserPromptSubmit`, the payload carries the prompt text: + +```json +{"hook_event_name":"UserPromptSubmit","prompt":"…"} +``` + +For `PreToolUse`, the payload carries the tool name and its full input: + +```json +{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"sleep 60","run_in_background":false,"timeout":30}} +``` + +For `SessionEnd`, the payload uses `reason` instead of `source`: + +```json +{"hook_event_name":"SessionEnd","reason":"prompt_input_exit"} +``` + +For `Stop`, the payload carries the agent's submission text and a retry flag: + +```json +{"hook_event_name":"Stop","stop_hook_active":false,"last_assistant_message":"…"} +``` + +`stop_hook_active` is `true` on every re-run that follows a previous Stop block in the same task; `false` on the first dispatch. When the agent's submission text is empty, `last_assistant_message` is sent as an empty string (not the literal word `Empty`). + +For `PermissionRequest`, the payload describes the action that triggered the permission dialog: + +```json +{"hook_event_name":"PermissionRequest","tool_name":"Bash","tool_input":{}} +``` + +`tool_name` is the tool category (`Bash`, `Edit`, `Read`, or an MCP tool name). `tool_input` contains the full serialized action. + +For `StopFailure`, the payload carries the matched error class and the underlying failure description: + +```json +{"hook_event_name":"StopFailure","error":"rate_limit","error_details":"429 Too Many Requests"} +``` + +`error` is the matcher target (one of the 9 values listed in the [StopFailure](#stopfailure) section). `error_details` is always present, but its source depends on the underlying failure category: for `rate_limit` it is the dynamic provider response (e.g. the body of a 429), for `model_refused` and `country_forbidden` it is the model-refusal / refusal text, and for failure categories that do not carry a runtime message (`authentication_failed`, `billing_error` from `CostExceeded`, `invalid_request`, `server_error` from `InferenceServerTimeout` / `BadResponseException`, `max_output_tokens`, `unknown` from `UnexpectedException`) it is a static description of the failure class rather than a provider-supplied string. + +The field names match Claude Code's `StopFailure` wire protocol, so the same hook script can be shared between agents. + + +## Run hooks in the background + +By default, a hook blocks the triggering action until it completes — the prompt waits for `UserPromptSubmit`, the tool waits for `PreToolUse`, and so on. For long-running tasks (test suites, deployments, external API calls) set `"async": true` on the hook command to run it in the background while the agent keeps working. + +```json +{ + "hooks": { + "PreToolUse": [ + { + "matcher": "Write|Edit", + "hooks": [ + { + "type": "command", + "command": "${HOME}/.junie/hooks/run-tests-async.sh", + "async": true, + "timeout": 300 + } + ] + } + ] + } +} +``` + +### How async hooks behave + +* The triggering action proceeds **immediately**; the hook starts in the background. The agent never waits for it. +* `decision`, `permissionDecision`, and `continue` in the hook's output have **no effect** — by the time the hook finishes, the action it would have controlled has already happened. They are logged and ignored. +* `systemMessage` is shown in the TUI as ` hook: ` when the hook completes, but it is **not** delivered to the agent. +* `additionalContext` is **queued in memory** and prepended to the agent prompt on the **next user submit** (matching Claude Code's "delivered on the next conversation turn" semantics). It is not retroactively injected into the in-flight task. If the session ends or the user starts a new session before the next submit, queued context for that session is lost. +* If the hook process times out (`timeout` field) or exits with a non-zero code, the failure is published as a TUI notification — async hooks are not silent. +* The `timeout` field is honoured the same as for sync hooks; the default is 10 seconds when omitted (600 seconds for `Stop`). +* If the `UserPromptSubmit` hook blocks the prompt (`decision: block`), already-queued async context from previous turns is restored and will reach the next successful submit. + +### When not to use it + +Use async only when the hook is genuinely advisory and the agent should not wait for its verdict. A `PreToolUse` lint check that you want to **block** a write on must stay synchronous: async cannot deny the tool. + +> `SessionStart`, `SessionEnd`, and `StopFailure` already run in the background at the executor level — Junie never waits for them. The `async` field has no effect on these events: setting `async: false` does **not** make them synchronous, and setting `async: true` does **not** change their behaviour either. + +## Failure handling + +Hook output and exit status do not block Junie startup: + +* Standard output and standard error are captured and logged at debug level. If a hook fails, captured output can be included in TUI error details, but it is not stored in session history. +* A non-zero exit code is logged as a warning and shown as a TUI error message. Junie continues to start. +* If the command exceeds its `timeout`, it is force-killed, logged as a warning, and shown as a TUI error message. Junie continues to start. +* Invalid hook configuration, such as an unsupported `type`, invalid `matcher`, or non-positive `timeout`, is shown as a TUI error message. Junie continues to start. + +Junie will not abort on hook failure; use the TUI system message and logs to diagnose failed hooks. + +## Stop hook blocking and retries + +A `Stop` hook can request the agent to retry submission by: + +* Exiting with status code `2`. The command's stderr is fed back to the agent as the block reason; if stderr is empty, a generic "blocked with exit code 2" message is used. +* Printing `{"decision":"block","reason":"…"}` to stdout on a successful exit. The `reason` is appended to the agent's state as an observer message so the agent can address the issue and submit again. +* Setting `blockOnError: true` on the hook command and exiting with any non-zero exit code. The command's stderr is fed back to the agent as the block reason. + +To guard against infinite block loops, the agent stops dispatching the Stop hook after 8 consecutive blocks within the same task and a system message is published. Override the limit with the `JUNIE_STOP_HOOK_BLOCK_CAP` environment variable; set it to `0` to disable the cap. + +A `Stop` hook can request a hard halt (no retry, the task ends with a failure exit status) by printing `{"continue":false,"stopReason":"…"}` to stdout on a successful exit. `continue: false` takes precedence over `decision: "block"`. Hard halts apply uniformly in interactive and batch mode: the task ends with a failure exit status. + +A `Stop` hook can send messages on a successful exit through two distinct JSON fields: + +* `{"hookSpecificOutput":{"additionalContext":"…"}}` (or a top-level `additionalContext`) — agent-facing payload, not shown in the TUI. Delivered to the agent as observer-message feedback in three cases: a `block` (retry), a `continue: false` hard-halt, **and** on a plain successful exit — in the latter case the conversation continues as non-error feedback (Claude parity). When the hook only emits `additionalContext` without `decision: block`, the agent runs one extra step with the context attached and then submits. The shared `JUNIE_STOP_HOOK_BLOCK_CAP` counter bounds runaway continuations the same way it bounds blocks. +* `{"systemMessage":"…"}` — user-facing payload. The `Stop` executor does not currently surface it in the TUI. + +Both fields are accumulated across all hooks that ran in the chain. + +## Merging hooks across configuration files + +When multiple configuration files define hook entries for the same event, all entries from all files are concatenated. +Higher-priority files do not override lower-priority files; their entries are appended. + +Only trusted sources participate in hook merging: user configuration and explicit `--config-location` files. +Default project-local `hooks` entries are skipped and reported as a hook configuration warning. + +For the configuration precedence order, see [Configuration files](Junie-CLI-configuration.md#configuration-precedence). + +## Limitations + +* The supported events are `SessionStart`, `UserPromptSubmit`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd`. +* `UserPromptSubmit` is currently triggered only from the interactive TUI; batch, ACP, and server hosts do not invoke it. +* `SessionStart`, `PreToolUse`, `Stop`, `StopFailure`, `PermissionRequest`, and `SessionEnd` are currently triggered from the interactive TUI and batch hosts; ACP and server hosts do not invoke them. +* `StopFailure` is observability-only — it cannot block, retry, or abort the agent. Output and exit code are ignored; `decision: block` and `continue: false` are demoted to TUI failure notifications. +* `StopFailure` fires only on classified LLM/API failures (the 9 `error` values listed in the [StopFailure](#stopfailure) section). Tool-execution failures, project pre-flight / shell-setup failures, and user-initiated cancellations do not fire it; the tool-error surface will be covered by a future `PostToolUseFailure` hook. +* Only `type: "command"` hooks are supported. +* Hooks within a single entry run sequentially. Parallel execution is not supported. +* `SessionEnd` hooks cannot block session termination, even if they return a non-zero exit code or `decision: block` in their stdout. +* `SessionEnd` dispatch has a total budget of 10 seconds across all matched entries combined; a longer per-command `timeout` will be effectively bounded by this overall budget. +* `Stop` hooks do not run for chat-type tasks. +* `blockOnError` is a Junie extension and is honoured for `Stop` hooks only. It is ignored on other events to avoid silently blocking prompt submission or session lifecycle. +* The `Stop` stdin contains only `hook_event_name`, `stop_hook_active`, and `last_assistant_message`. +* On `/new` or any other interactive session switch, the outgoing session is not terminated — it continues running in the background, so its `SessionEnd` hook is **not** dispatched on the switch. Only the incoming session's `SessionStart` hook fires (with `source: clear` for a fresh `/new`, `source: resume` for a cold-loaded resumed id). Re-foregrounding a session that is already live in the same CLI process fires no hooks at all — neither `SessionStart` nor `SessionEnd`. +* Hook output is discarded for `SessionEnd`. For `PreToolUse`, `additionalContext` is added to the model context and `updatedInput` can replace the tool's input for that call. +* The `SessionStart`/`UserPromptSubmit`/`SessionEnd` executors log `continue: false` as a failure but do not yet halt the session, cancel the prompt, or abort startup. Only `Stop` maps `continue: false` to a real abort action. +* `additionalContext` on stdout — agent-facing, never published to the TUI. For **sync** hooks: `UserPromptSubmit` prepends it to the prompt; `Stop` folds it into the agent's observer message on block / hard-halt retries **and** on a plain successful exit (Claude-style continue, see [Stop hook blocking and retries](#stop-hook-blocking-and-retries)); `PreToolUse` adds it to the model context for that tool step; `SessionStart`, `SessionEnd`, and `PermissionRequest` ignore it. For **async** hooks (`async: true`): the field is queued and prepended to the next user submit regardless of the originating event. +* `systemMessage` on stdout — user-facing TUI info message, published as ` hook: `. For **sync** hooks it is honoured by the `SessionStart`, `SessionEnd`, and `UserPromptSubmit` executors. For **async** hooks it is published on completion for any event that supports `async: true`. +* `PermissionRequest` hooks fire for all permission dialogs regardless of whether the agent triggered the action autonomously or the user requested it directly. + +### Reference + +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | + +### Plan mode + +# Plan mode + + + + + Shortcut to toggle Plan mode: Shift+Tab + + +In Plan mode, Junie CLI analyzes the codebase with read-only operations and produces a design document for the task +before any code is written. You can review the plan, push back on assumptions, and adjust the scope — and only then +let Junie CLI implement it. + +## How Plan mode works + +When Plan mode is enabled, Junie CLI focuses on understanding the task and shaping a concrete implementation plan rather +than modifying the project: + +- Junie CLI uses read-only operations to explore the codebase, configuration, and any context attached to the prompt. +- Instead of editing files, Junie CLI produces a plan that captures the scope, key decisions, and the reasoning behind + them. +- The plan is treated as a living design document: when requirements change in the same session, the plan is + updated alongside them. +- Once the plan is confirmed, Junie switches to implementation and applies the changes described in the plan. + +Plan mode is most useful for non-trivial tasks where alignment on intent and approach matters more than producing +code as fast as possible. + +## Enable Plan mode + +You can enable Plan mode in the following ways: + +- Press `Shift+Tab` in the prompt area to toggle between the default mode and Plan mode. +- Run the `/plan` slash command to toggle Plan mode. To start in Plan mode with your prompt submitted immediately, + type `/plan `, for example: + + ``` + > /plan refactor commands + ``` + +- Use the `--plan` command-line flag to start Junie CLI directly in Plan mode. Combine it with `--prompt` + to auto-submit a prompt in plan mode: + + ```bash + junie --plan + junie --prompt "Refactor the commands module" --plan + ``` + +![](plan_mode_enabled.png){width="706"} + +When Plan mode is active, the prompt area shows a corresponding indicator, and the agent's behavior changes to +plan-first. + +## Review and refine the plan + +After Junie CLI proposes a plan, the session pauses and waits for your input. The prompt area shows a set of actions +you can pick from: + +- **Confirm and implement**: accept the plan and let Junie CLI proceed with the implementation using the agreed-upon + scope and decisions. +- **View the entire plan** (`Ctrl+P`): open the dedicated plan view with the full design document. +- **Open ``**: open the saved plan file (Markdown) in your default editor or viewer. +- **Save the plan and stop**: keep the plan file on disk and end the session without implementing it. + +![](plan_actions.png){width="706"} + +You can iterate on the plan as many times as needed before implementation starts. This keeps course corrections +cheap — adjusting a plan is much faster than reverting code that does not match your intent. + +## Plan view + +Press `Ctrl+P` at any time during a plan-mode session to open the dedicated plan view. The plan view shows the +proposed design document split into tabs. The exact set of tabs depends on the task and may vary between sessions, +but typically you will see something like: + +- **Requirements**: what the change should achieve: goals, scope, user stories, functional and non-functional + requirements. +- **Technical design**: how the change is going to be implemented: the affected modules, key decisions, + data flows, and trade-offs. +- **Testing**: the test strategy and specific test cases that will verify the implementation. +- **Delivery steps**: the concrete steps Junie CLI plans to take during implementation, in order. + +Simple tasks may have fewer sections, while more complex tasks may include additional design sections alongside +the delivery steps. + +![](plan_view_tabs.png){width="706"} + +Use `Tab` or the arrow keys to switch between tabs. Press `Ctrl+P` again to return to the chat. + +## Related documentation + +- [Quickstart](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Debug mode + +# Debug mode + + + + + Slash command to switch to Debug mode: /debug + + +Debug mode turns Junie CLI into an AI debugging assistant. Instead of editing source code, Junie CLI launches or +attaches to a running program, manages breakpoints, inspects runtime state, and evaluates expressions in the +currently paused execution frame. + +Use Debug mode for problems that are easier to investigate at runtime than by reading code — flaky behavior, +unexpected variable values, or tracking down where execution actually goes. + +## How Debug mode works + +In Debug mode, Junie CLI operates against a live debugger session connected to a JetBrains IDE. The agent uses a +specialized set of tools focused on runtime inspection and execution control rather than source code modification: + +- **Session control:** Launch a new debug session, attach to an existing process, resume execution, or step through + code (step over, step into, step out). +- **Breakpoint management:** Set line and exception breakpoints, remove existing ones, and list all active + breakpoints in the project. +- **State inspection:** Inspect variables in the current scope, view the call stack for all threads, and switch + between threads and frames. +- **Expression evaluation:** Evaluate expressions or code fragments in the context of the currently paused frame. + +Junie CLI does not modify source code while in Debug mode unless you explicitly ask for a change that is compatible +with the current execution state. + +### Example interactions + +- _"Why is `x` null?"_ — Junie CLI inspects the current paused frame, retrieves the value of `x` and the surrounding + context (call stack, related variables), and explains the state. +- _"Stop at line 42 in `Main.kt`."_ — Junie CLI sets a line breakpoint at the requested location. +- _"What is `list.size()`?"_ — Junie CLI evaluates the expression in the current frame and reports the result. + +## Requirements + +Debug mode is only useful when Junie CLI can talk to a debugger. Make sure the following is in place before +enabling Debug mode: + +- Junie CLI is connected to a JetBrains IDE with debugging support. For details on the IDE integration, see + [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). +- The IDE has a debug session active, or you are ready to ask Junie to start or attach to one. + +If no IDE with debugging support is connected when you try to enable Debug mode, Junie CLI reports that +"Debug mode requires an IDE with debugging support connected" and stays in the default mode. + +## Enable Debug mode + +To toggle Debug mode, use the `Shift+Tab+Tab` shortcut or run the `/debug` slash command in the Junie CLI prompt: + +``` +> /debug +``` + +Using the same shortcut or running `/debug` again disables Debug mode and returns Junie CLI to the default mode. + +## Related documentation + +- [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md) +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) + +### Remote mode + +# Remote mode + + + + + Slash command to switch to Remote mode: /remote + + +Remote mode lets you open your running Junie CLI session in a web browser and keep working on the same task from +another device. The Junie CLI process keeps running in your terminal — Remote mode adds a synchronized web UI on top +of it. + +## How Remote mode works + +When you start Remote mode, Junie CLI opens a secure tunnel to the Junie web app and streams the session into a +web UI: + +- The CLI session continues to run in your terminal, on your machine. +- The web UI shows the same chat history, progress, interactive prompts, and task status. +- Anything you send from the web UI — prompts, replies to approval requests, plan refinements — is routed + back to the same running session. + +Both the terminal and the web UI work against a single shared session, so you can switch between them at any time +without losing context. + +> Your machine must stay awake while a remote session is active. If the computer goes to sleep, the CLI process is +> suspended and the web UI cannot communicate with it until you wake the machine. +> {style="note"} + +## Requirements + +Remote mode requires a Junie subscription: + +- Sign in with your JetBrains Account, or +- Use a `JUNIE_API_KEY` access token. + +[Bring Your Own Key (BYOK)](BYOK.md) on its own is not enough — Remote mode itself goes through the Junie service +and requires one of the two options above. + +> Remote mode is not available when Junie CLI is signed in through **JetBrains AI Enterprise**. To use Remote +> Mode, sign in with your JetBrains Account or a `JUNIE_API_KEY` instead. See +> [Manage your account](Junie-CLI.md#manage-your-account). +> {style="warning"} + +## Start a remote session + +1. In Junie CLI, in a new or running session, run the `/remote` command. + + ``` + > /remote + ``` + +2. On the **Remote mode** screen, select **Start Remote Session**. + + Junie CLI creates the tunnel and prints a confirmation message with the connection URL. + +3. Open [`junie.jetbrains.com/remote`](https://junie.jetbrains.com/remote) in your browser. + + The web app connects to your running CLI session and replays the chat history. After that, the terminal and + the browser stay in sync. + +> Run `/remote` again to see the status of the active remote session, including connection state and the option to +> stop it. + +## What you can do from the web UI + +The web UI exposes the most common actions for continuing a task: + +- Send a new prompt to the agent. +- Reply to interactive requests (approve or decline an action, answer a question, pick an option). +- Cancel the current task. +- Continue the task after the step limit is reached. +- Toggle [brave mode](Junie-CLI.md#brave-mode). +- Refine a proposed plan in [plan mode](Junie-CLI-Plan-Mode.md), or confirm a plan and ask the agent to + implement it. + +## Limitations + +The web UI is intentionally narrower than the terminal. It is built to keep working on an existing CLI session, +not to fully replace the terminal: + +- Slash commands such as `/new`, `/history`, `/account`, `/model`, `/usage`, `/ide`, `/mcp`, `/quit`, and custom + slash commands are available only in the terminal. +- Shell commands invoked with `!` in the prompt are terminal-only. +- File and folder picking with `@` is not available in the web UI. +- Drag-and-drop of files and images is not available in the web UI. +- Prompt history search (`Ctrl+R`) and the session transcript view (`Ctrl+O`) are terminal-only. +- Only one web client can be connected to a remote session at a time. Opening the URL from another tab or device + takes over the connection from the previous client. + +If you need any of these features, switch back to the terminal — the session is the same, and your changes from +the web UI are already there. + +## Stop a remote session + +To stop sharing the current session with the web app: + +1. Run `/remote` in the terminal. +2. On the status screen, select **Stop Remote Session**. + +Stopping a remote session does not affect the underlying CLI session — you can continue working in the terminal +or start a new remote session later. + +## Related documentation + +- [Using Junie in the terminal](Junie-CLI.md) +- [Slash commands reference](Slash-commands.md) +- [Quickstart](Junie-CLI.md) + +### Parallel sessions and worktrees + +# Parallel sessions and worktrees + + + + + Start another live session with /new, switch sessions with /history, and isolate file changes with /worktree. + + +Junie can keep multiple live sessions in one interactive terminal. You can start another task, let existing +sessions continue in the background, and switch back to them later without losing their scrollback or current state. + +Parallel sessions share the file system of the project or worktree they are running in. When you want several sessions +to make code changes at the same time, use [Git worktrees](https://git-scm.com/docs/git-worktree) so each task works in +its own checkout. + +## Start another session + +Use `/new` when you want to start another task without quitting the current Junie instance. The current session stays +live in the background, and Junie opens a new interactive session. + +To start with text already in the prompt, add it after the command: + +```text +/new update the tests for the payment flow +``` + +Use this workflow when you need to keep one task available while you investigate or work on another one: + +1. Start a task in Junie. +2. Run `/new` or `/new ` to open another live session. +3. Work in the new session while the previous live session stays available in Task history. +4. Use `/history` to switch between live sessions when you need to return to another task. + +## Switch with Task history + +Run `/history` to open **Task history**. It lists live sessions from the current Junie instance together with saved +sessions from previous runs. Start typing to search the list, select a row to open that session, or press `Esc` to return +to the current session. + +By default, Task history shows sessions from **all directories**. Press `Tab` to narrow the list down to **project +directory**, showing only sessions whose stored project directory matches the current project; press `Tab` again to +go back to all directories. The active scope is shown next to the "Task history" title, and the text search box +keeps filtering on top of whichever scope is active. + +Task history shows the task name, project, and status or last activity time. + +| Status | Meaning | +|--------|---------| +| `Working…` | The live session is currently running a task. | +| `Awaiting input` | The live session is waiting for your reply, approval, or another interactive choice. | +| `Ready` | The live session is idle and ready to continue. | +| Relative time, such as `5m ago` | The row is a saved session that is not currently live in this Junie instance. | +{width="706"} + +Switching to a live session does not restart it. Junie brings that session to the foreground with its existing +conversation and terminal output preserved. + +### Cross-process sessions + +Task history can also show live sessions that are open in another Junie instance. These rows are dimmed and cannot +be opened from the current instance. + +To continue one of those sessions, switch to the terminal where that Junie instance is running. This prevents two +terminal UIs from controlling the same live session at the same time. + +## Use worktrees to isolate file changes + +Parallel sessions do not isolate files by themselves. If two sessions work in the same project directory, they can edit +the same files and overwrite each other's changes. For simultaneous code changes, give each task its own Git worktree. + +A Git worktree is a linked checkout of the same repository in a separate directory. Each worktree has its own working +tree and index, so different branches can be checked out simultaneously. + +### The `/worktree` command + +Run `/worktree` to open the worktree menu. From there you can: + +- **Switch to an existing worktree**: select one of the worktrees already created for this repository. +- **Create a new worktree**: Junie creates a new Git worktree with a predefined name, such as + `-junie-wt-01`, `-junie-wt-02`, and so on, as a sibling directory of your project. +- **Switch back to the original project**: return to the main working directory. + +After switching, Junie resets the current session state for the new worktree. Use `/worktree` before starting a new +task or at the beginning of a new live session. + +### Safe parallel-work workflow + +1. Start a separate live session with `/new`. +2. In that session, run `/worktree` and switch to an existing worktree or create a new one. +3. Ask Junie to create or switch to the branch for that task. +4. Work on the task in that worktree while other sessions use their own directories. +5. Use `/history` to switch between the live sessions. + +If you often work this way, pre-create a few worktrees so build caches are ready before you start parallel tasks. + +### Transferring uncommitted changes + +If the current working directory has uncommitted changes when you switch to a worktree, Junie asks whether to move +them to the target workspace or start clean: + +- **Transfer changes to workspace**: Junie uses `git stash` to move uncommitted changes from the source directory to + the target worktree. +- **Start with a clean workspace**: the target worktree starts with no uncommitted changes. + +If the stash cannot be applied cleanly, for example because of conflicts, Junie reports the issue and leaves the +changes in the stash so you can resolve them manually. + + +## Limitations + +- Worktree support requires a git repository. It is not available for projects that are not tracked by git. +- Worktree directories are created as siblings of the project directory, for example `../my-project-junie-wt-01`. Make + sure the parent directory is writable. + +### Code review agent + +# Code review agent + + + +Slash command to invoke local code review: /review + +Junie's code review feature uses a tailored subagent with optimized resource consumption for code review tasks: +instead of running a full agent session, it uses a more focused system prompt and a subset of read-only tools, +focusing on the changed lines of code. + +> Local code review can only be run on projects in Git repositories. +> {style="note"} + +Use local code review when you want to get a quick sanity check before opening a pull request, +review your own changes after a long coding session, or review your current branch against `main`. + + +## How it works + +To run a local review of code changes, Junie CLI: + +* **Loads the relevant code diff** according to the user-defined request scope. +* **Uses a focused prompt and toolset**: the agent can open files and search the project to understand context, but it never edits files, runs builds or tests, creates files, or commits and pushes changes. +* **Follows your guidelines and skills**: the agent reads project guidelines and any code-review-related [agent skills](Agent-Skills.md) and applies their instructions. +* **Supports follow-ups**: the review runs as its own session that can be resumed, so you can ask follow-up questions such as *"Is the fix I just pushed good enough?"* without re-explaining the context. + + +## Usage + +### Standard checks + +When you invoke the `/review` slash command, Junie CLI detects the Git state of your project and opens a wizard with available review targets: + +- **From Main**: compares your current branch against `main`. Shown only when a `main` branch exists, and you are not currently on it. +- **Last Commit**: reviews the changes introduced in the most recent commit. +- **Unstaged Changes**: reviews the code you have modified but not yet committed. + +![](review_wizard.png){width="706" border-effect="line"} + +### Custom instructions + +You can scope the review to a specific concern or set of changes by adding plain-text instructions after the command: + +```console +/review focusing on performance and memory leaks +``` + +```console +/review the last two commits +``` + +Junie CLI will prioritize your instructions while still performing its standard review checks. + +## Navigating review results + +Junie CLI presents the findings in a dedicated review screen where you can: + +* Browse the list of suggestions grouped by file. +* View the relevant code context for each of the suggestions. +* Accept or dismiss suggestions one by one, or select several suggestions and accept or dismiss them at once. + +Critical findings, such as security vulnerabilities, crashes, data loss, or correctness issues that break functionality, +are prefixed with a `[CRITICAL]` label. When a fix is simple and safe, Junie CLI includes a ready-to-apply code suggestion. + +Closing the review screen finishes the review and returns you to the task screen, keeping the review as part of the same +session history. + +## Also available in + +- **Headless mode**: Use the `--review` flag with the `junie` command in your terminal. You can optionally provide + a natural language description to guide the review. + + ```console + # Review current changes in the repository + junie --review + + # Review changes with specific instructions + junie --review "Check for potential null pointer exceptions in the new logic" + + # Compare with a specific branch + junie --review "Compare my changes with the develop branch" + ``` +- **GitHub CI/CD pipelines**: To trigger Junie's code review agent on opened or updated GitHub pull requests, use the + [Junie GitHub Action](Junie-on-GitHub.md) for automated code reviews. + See the [cookbook](Automated-code-reviews.md) for details. + +### Demo agent + +# Demo agent + + + + + +Slash command to invoke the demo agent: /demo + +> This feature is currently in the [Early Access Program](Junie-CLI-EAP.md). To try it, +> [install the Early Access version](Junie-CLI-EAP.md#install-eap) of Junie CLI. + +The `/demo` slash command launches a **visual demo** of your project. Junie CLI +spins up a disposable virtual machine, builds and starts your app inside it, +and then drives the running UI — clicking, typing, and taking screenshots — to show +that a feature or recent change works. The result is a structured Markdown +answer in the TUI plus a folder of [output artifacts](#output-artifacts) — +screenshots, a screen recording, and a self-contained HTML report — that you +can share or attach to a PR. + +Think of it as **'show me, don't tell me'**: instead of asking Junie to read +code and explain a change, you ask Junie to *use* the app and prove the change +is real on screen. + +## Prerequisites + +`/demo` requires: + +* **Docker running on your machine.** This is the most important prerequisite — + the demo VM is a Docker container, and `/demo` will not start without a + working Docker daemon. If `docker ps` doesn't work in your terminal, + `/demo` won't work either. Start Docker Desktop before running `/demo`. +* **A model with Computer Use support.** Right now only **GPT‑5.4 and newer** + (GPT‑5.4, GPT‑5.5) are supported. More models will be added later as + Computer Use becomes available on them. If your active model doesn't + qualify, `/demo` refuses to start and shows the supported list. See + [Junie CLI Model selection](Junie-CLI-Model-selection.md). +* **A demo VM image** at `.junie/vms//Dockerfile`, layered on top of + the base image `registry.jetbrains.team/p/junie-cli/containers/demo-base:2`. + The base is Debian bookworm and ships Chromium, Node.js, xterm, ffmpeg, + xdotool, screenshot tooling and a headless Xvfb desktop with a window + manager — everything Computer Use needs to drive a desktop or web app. + The first time `/demo` runs in a project with no VM template, Junie + seeds a starter one for you — see [First-run setup](#first-run-setup). + Add the runtimes your app needs on top, as shown in + [Customizing the demo](#customizing-the-demo). + +## Quick start + +You have two ways to set up `/demo` for a project: **author the files by +hand** as shown below, or **skip authoring** and let `/demo` create +starter versions for you on the first run (see +[First-run setup](#first-run-setup)). + +For projects that need anything beyond "open a browser at localhost", you'll +typically set up three things in your repo: + +1. **A custom image on top of `demo-base`.** Create + `.junie/vms//Dockerfile` that starts with + `FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2` and adds + the runtimes your app needs (JDK, Node, Python, system packages…). The + base already handles the display stack — don't reinstall it. + + Node example: + + ```dockerfile + # .junie/vms/node-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends nodejs npm + ``` + + Python example: + + ```dockerfile + # .junie/vms/python-vm/Dockerfile + FROM registry.jetbrains.team/p/junie-cli/containers/demo-base:2 + RUN apt-get update && apt-get install -y --no-install-recommends python3 python3-pip + ``` + +2. **Mounts (optional).** The project root is always mounted at `/workspace` + automatically — you don't need to configure that. For extra bind mounts + (host credentials, fixture data, prebuilt artifacts on the host), create + a text file at `.junie/vms//mounts` (no extension, **not a + directory**) with one mount per line: + + ```text + # :[:ro|:rw] + # $HOME and ${HOME} are expanded from the environment. + # Lines starting with # are ignored. + $HOME/.config/my-app:/root/.config/my-app:ro + /tmp/my-fixtures:/workspace/fixtures + ``` + + Missing host paths are skipped with a warning — Junie won't refuse to + start the VM because of a stale mount line. + +3. **A `.junie/demo.md` file** telling the agent which VM to use and how to + build/launch the app. The **`vm:` value must match the subdirectory name + you created in step 1** — that's how Junie binds the file to your + Dockerfile. + + Node project — `vm: node-vm` matches `.junie/vms/node-vm/`: + + ```markdown + # My web app + + vm: node-vm + + ## Build inside the VM + npm install && npm run build + + ## Launch + npm run start & + # ready when http://localhost:3000 responds 200 + ``` + + Python project — `vm: python-vm` matches `.junie/vms/python-vm/`: + + ```markdown + # My Python app + + vm: python-vm + + ## Build inside the VM + pip install -r requirements.txt + + ## Launch + python app.py & + # ready when http://localhost:5000 responds 200 + ``` + + Shortcut: if you only ever need one VM, you can skip the subdirectory and + put the Dockerfile straight at `.junie/vms/Dockerfile`. Then reference it + in `.junie/demo.md` as `vm: default`. + +Now `/demo` will pick up your custom image, mounts, and launch instructions +automatically. + +## Basic usage + +The command takes no arguments: + +```text +/demo +``` + +### Choosing what to demo + +Junie asks **what you would like it to demo** and offers a short list of scopes +to choose from, with a text field right below it for +[describing the demo yourself](#describing-the-demo-yourself) (navigate with +the arrow keys, Enter to pick, Esc to cancel): + +* **Changes of this branch (vs `origin/main`)** — everything the current + branch adds on top of the default branch, including changes you haven't + committed yet. The ref in the label is the default branch Junie resolved + for your repository (`origin/main`, `origin/master`, `main`, or `master`). +* **Changes from this session** — the messages you exchanged, the files Junie + touched, the task it just finished. You don't have to repeat what was done; + the demo agent already sees it. +* **Uncommitted changes** — your working tree compared to `HEAD`. Files that + aren't tracked by git yet are picked up too. +* **Last commit** — the last commit compared to its parent. +* **Smoke test — find anything broken** — Junie drives the app's main flows + looking for breakage and reports what works and what doesn't. + +The list adapts to your project: the branch scope only shows up when you're +not on the default branch, **Uncommitted changes** only when the working tree +is dirty, **Last commit** only when there is a commit to compare against. +Outside a git repository (or when git isn't installed) you get the session +scope and the smoke test. + +For the three git scopes the **diff is the specification of the demo**: Junie +reads it first, lists every user-visible change in it, and demonstrates them +one by one instead of stopping at the first one. This is the most common way +to use `/demo`: you've just had Junie implement or fix something, and you +want to *see* it working before you commit — type `/demo`, hit +Enter, and pick the scope that matches what you want to see. + +### Describing the demo yourself + +None of the scopes has to fit: the picker always has a free‑form field below +the list. Press ↓ past the last scope to get into it, and type what +you want to see in plain natural language: + +```text +show the new dark-theme toggle in Settings +open the search dialog and find 'TODO' +log in as user@example.com and open the profile page +``` + +Enter starts the run, ↑ takes you back to the list of +scopes, Esc cancels. The request is passed to the demo agent +verbatim, so the more concrete it is, the tighter the demo. Such a request is +treated as self‑contained — Junie won't go hunting through git history to find +unrelated context. + +### Demoing a specific feature from scratch + +When you want a demo of an existing feature (not a recent change), name the +feature explicitly in the same text field: + +```text +the file-tree drag-and-drop in the sidebar +``` + +Junie will resolve how to reach it (menu item, hotkey, URL, etc.) and walk +through it. + +## What happens when you run `/demo` + +A `/demo` run goes through four phases. Knowing the phases helps you interpret +what's on screen at any moment. + +### 1. Plan + +Before any VM starts, Junie writes a short **visible demo plan** — +an ordered list of user‑visible milestones, e.g.: + +```text +1. Launch the app — main window shows the file tree. +2. Open Settings via the gear icon — Settings dialog appears. +3. Toggle "Dark theme" — UI re-renders in dark colors. +4. Close Settings — main window remains in dark mode. +``` + +When the run is scoped to a diff — one of the git scopes of the picker, or a +review-style request — Junie reads that diff before planning and turns every +user-visible change in it into a milestone, so the plan covers the whole +change set. + +The plan is your contract with the agent. If a step looks wrong, interrupt +with Esc and adjust the request before the VM starts. + +### 2. Build and launch + +Junie: + +1. (Optionally) builds artifacts on **your host machine** — but only if + `.junie/demo.md` explicitly asks for it. By default nothing is built on the + host. +2. Starts the VM (`vm_start`). Your project root is mounted at `/workspace` + inside it. +3. Builds the project inside the VM (commands come from `.junie/demo.md` + if present, otherwise Junie figures them out). +4. Launches the app in the background and waits for it to be ready + (health endpoint, log line, or just a visual wait). + +A blank screen right after `vm_start` is normal — the app hasn't started yet. + +### 3. Demonstrate + +Junie drives the running app via Computer Use: clicks, keystrokes, +screenshots. The TUI shows a `Working… esc to stop` indicator while the agent +is acting. Each action is followed by an automatic screenshot, so you'll see +the run progress step by step. + +If a visual attempt fails 2–3 times and Junie can't figure out the next step +from the screen, it falls back to **targeted code lookups** (grep + open +file). This is allowed but rare — the primary source of truth is the running +app, not the source code. + +### 4. Finish + +Junie CLI shuts down the VM (`vm_stop`) and writes a structured Markdown report +with two main sections: + +* **What has been tested**: the steps that ran and what was visible. +* **Result**: pass / fail / partial, plus any issues spotted. + +The screenshots, video, and HTML report from the run are saved alongside +the session — see [Output artifacts](#output-artifacts) for the exact paths. + +## Stopping a demo + +* Press Esc while the `Working…` indicator is visible to interrupt + the agent. The VM is shut down cleanly. +* The agent won't launch the VM twice in one session unless you explicitly + ask. + +## Output artifacts + +After a `/demo` run finishes, you get a folder of artifacts on disk that you +can share, attach to a PR, or rewatch later. They live under your Junie home +directory, grouped by session: + +```text +~/.junie/sessions//demo/ +├── screenshots/ PNG screenshots captured during the run +│ └── shot_20260520_120005_000.png … +├── demo.mp4 screen recording of the VM (if recording finished) +├── captions.vtt caption track aligned to the video +└── report.html self-contained HTML report +``` + +What each one contains: + +* **`report.html`**: the main artifact. A single self-contained page with the + user request, the agent's Markdown answer ('What has been tested' + result), + the embedded video, and the screenshots inline. This is what you usually + attach to a PR or send to a teammate. +* **`demo.mp4`**: the screen recording. Only present if the recorder + started and was stopped cleanly before VM teardown. Embedded inside + `report.html` too. +* **`captions.vtt`**: WebVTT caption track generated from screenshot + timestamps. Used by `report.html` to label moments in the video. +* **`screenshots/`**: every screenshot Computer Use took during the run, + one PNG per `computer` call. + +The Markdown answer the agent shows in the TUI is **not written to a +separate file** — it lives in the session transcript and inside +`report.html`. If you want the raw text, copy it from the TUI or open the +report. + +**Persistence:** artifacts are kept across sessions — nothing is auto-cleaned. +If you want them gone, delete the session folder under `~/.junie/sessions/` +manually. + +## Customizing the demo + +`.junie/demo.md` tells the demo agent project‑specific build and launch +commands. Use it when 'how to start the app' isn't obvious from the source +tree. The [Quick start](#quick-start) above shows the basic structure; this +section lists the kinds of things you can usefully put inside. + +Common things to put in `.junie/demo.md`: + +* **`vm: `** — required. The agent passes this value to `vm_start` as + the template name, and the action fails if it's missing. The name must + resolve to a Dockerfile under `.junie/vms/`: either a subdirectory + (`.junie/vms//Dockerfile`) or the literal value `default` for the + top-level `.junie/vms/Dockerfile`. +* The exact build command(s) to run inside the VM. +* The launch command — always background it (`&` or `nohup … &`). +* A health check Junie can wait on before interacting with the UI. +* Whether the jar/binary should be built on the host first (and the exact + `bash` command to do it — Junie will only run it if you explicitly ask). + +## First-run setup + +If you haven't configured `/demo` for this project yet — meaning no +`.junie/vms//Dockerfile` exists — the first run won't start a real +demo. Instead, Junie seeds a starter configuration for you and asks how +you want to proceed. Two files appear in your project: + +### What gets seeded + +* **`.junie/demo.md`** — the project-level guide that tells the demo agent + which VM to use and how to launch your app. The file is free-form + Markdown; the agent reads it as instructions before doing anything. Two + things in it are essential: + + - **`vm:`**: the name of a subdirectory under `.junie/vms/`. The + seeded file already has `vm: template-vm` wired up. + - **The launch command**: how to start your app inside the VM. Goes + under the `## Running inside the VM` section. + + Everything else is optional. Useful things to grow `demo.md` with later + include: host-side build steps you want Junie to run, environment + variables, test users, known quirks, or links to other docs. + +* **`.junie/vms/template-vm/Dockerfile`** — the VM image. Extends + `registry.jetbrains.team/p/junie-cli/containers/demo-base:2` — see + [Prerequisites](#prerequisites) for what the base ships. Add the apt + packages and language runtimes your app needs on top. + +### Filling it in + +Right after seeding, Junie shows you the two files and offers a choice +(navigate with the arrow keys, `enter` to pick): + +* **Yes, fill them in for me** — Junie inspects your project (package + manager, dev/start command, port, extra runtimes) and fills in the launch + command in `demo.md` and the `Dockerfile` for you. Review what it wrote, + then re-run `/demo`. +* **No, I'll do it myself** — Junie leaves the seeded files untouched so you + can edit them by hand. + +You can also trigger the automatic fill-in later — ask Junie to "set up +`/demo`", or invoke the `demo-setup` skill with `$demo-setup`. Either way +Junie only edits `demo.md` and the VM `Dockerfile`, and leaves the final +review and the real demo run to you. + +### After editing + +Once both files are filled in, re-run `/demo`. Junie will pick up the new +VM template and start a real demo run. The seed only fires when no VM +template exists yet — once `.junie/vms/` has any Dockerfile, your +configuration is treated as authoritative and Junie leaves it alone. + +If you mess something up and want to start over, delete `.junie/vms/` +(and optionally `.junie/demo.md`) and re-run `/demo` — the seed will fire +again. + +> **Note:** the seeded `demo.md` carries explanatory HTML comments at the +> top describing what each section is for. Once your file is in good +> shape, delete those comments so the agent context isn't bloated by +> generator boilerplate it doesn't need. + +If you'd rather author `.junie/demo.md` and the Dockerfile from scratch +without using the seeded starter, just create them yourself before the +first `/demo` run — the seed only fires when nothing is there. + +## Multiple VM templates in one project + +`.junie/vms/` is a directory — you can put **as many VM subdirectories +under it as you want**, each with its own Dockerfile (and optionally its +own `mounts` file). A typical layout for a project that ships several +VMs side by side: + +```text +.junie/ +├── demo.md +└── vms/ + ├── backend-vm/ + │ ├── Dockerfile + │ └── mounts + ├── frontend-vm/ + │ └── Dockerfile + └── cli-vm/ + └── Dockerfile +``` + +All templates discovered under `.junie/vms/` are listed to the demo agent +on every `/demo` run, so it can pick the right one according to the +instructions in `.junie/demo.md`. + +## Examples + +### Verify a fix you just made + +```text +> fix the bug where the search box loses focus after typing one character +…Junie edits files, runs tests… +> /demo +…pick "Changes from this session" (or "Uncommitted changes") +``` + +Junie picks up the change, opens the search box, types several characters, +and shows that focus stays. + +### Demo a feature in a fresh repo + +```text +> /demo +…press ↓ past the last scope to reach the text field +> open the project, run the example notebook, show the chart it produces +``` + +Useful for onboarding videos or PR descriptions. + +### Compare a 'before / after' change + +```text +> /demo +…press ↓ past the last scope to reach the text field +> show the old behavior, then the new behavior of the export button +``` + +If the session history doesn't contain a clear "before" state, Junie will +note that in the report instead of inventing one. + +## Troubleshooting + +**'Demo agent requires access to a model with computer use support…'** +: Your active model isn't on the supported list. Today that list is +GPT‑5.4 and GPT‑5.5; more models will land later. Switch via +[Junie CLI Model selection](Junie-CLI-Model-selection.md). + +**The VM starts but the screen stays blank** +: Normal in the first few seconds after `vm_start`. If it persists, the app +probably failed to launch — check `.junie/demo.md` for the right build/launch +commands, or add a health check Junie can wait on. + +**Junie keeps reading source files instead of clicking** +: This usually means the entry path (how to reach the feature) isn't obvious. +Describe the entry path yourself in the request field, for example +`open Settings via Cmd+, and toggle X`. + +**`/demo` is disabled / greyed out** +: Either Docker isn't running, or no Computer Use model is available for +your account. + +## Related + +* [Slash commands](Slash-commands.md) — full list of slash commands. +* [Junie CLI Model selection](Junie-CLI-Model-selection.md) — picking a model + that supports Computer Use. + +### Junie CLI: What is stored on the user's disk + +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers + + diff --git a/junie/versions/2651.6/skills/junie-cli-docs/Slash-commands.md b/junie/versions/2651.6/skills/junie-cli-docs/Slash-commands.md new file mode 100644 index 0000000..5560486 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/Slash-commands.md @@ -0,0 +1,79 @@ +# Reference + +Complete reference for the slash commands (`/`) and shortcuts available in Junie CLI (interactive mode). + +## Built-in slash commands + +> Commands shown with `<...>` accept optional raw trailing text: Junie CLI passes everything after the command token +> as one argument. +> +> For example, `/new fix failing tests` opens another live session with `fix failing tests` in the prompt. `/plan refactor commands` +> enables plan mode and submits `refactor commands` immediately. +> +> Commands without `<...>` do not accept arguments. + +{id="optional-text-as-arguments"} + +| Command | Description | +|--------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `/account` | Manage your Junie Accounts and Junie API keys, or connect your own API key from Anthropic, OpenAI, and other OpenAI API-compatible providers. | +| `/brave` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On) that control how much Junie CLI relies on user approval before running potentially sensitive actions. | +| `/commands` | Create and manage custom slash commands. | +| `/copy [N]` | Copy an assistant response to the clipboard. Without `[N]`, copies the most recent response. With `[N]`, copies the Nth-latest response (`1` = most recent, `2` = the one before that, and so on). | +| `/debug` | Toggle [debug mode](Junie-CLI-Debug-Mode.md), in which Junie CLI acts as an AI debugging assistant against a live debugger session in a connected JetBrains IDE. Shortcut: `Shift+Tab+Tab`. | +| `/demo` | Launch a [visual demo](Junie-CLI-demo.md) of a feature inside a disposable VM. Junie asks [what to demo](Junie-CLI-demo.md#choosing-what-to-demo) and offers scopes based on the state of your repository: the changes of the current branch, uncommitted changes, the last commit, the changes of the current session, a smoke test, or a request you [describe yourself](Junie-CLI-demo.md#describing-the-demo-yourself). | +| `/effort` | Set the reasoning [effort level](Junie-CLI.md#model-and-effort) for the current model. The set of supported effort levels depends on the selected model. | +| `/extensions ` | Browse, install, update, and manage [Junie CLI extensions](Junie-CLI-Extensions.md) — bundles of agent skills, MCP servers, subagents, custom commands, and guidelines. | +| `/feedback ` | Share feedback about the current session with the Junie team. If you provide ``, Junie opens the feedback screen with that text as an editable draft. A ZIP file with the current session logs is automatically attached to the submitted feedback response. | +| `/history` | Open Task history to search sessions, switch between live sessions, or resume a saved session from a previous run. Press `Tab` to toggle between sessions from all directories and only the current project directory. | +| `/ide` | Show the current JetBrains IDE connection status and the JetBrains IDE features available to the current session. For details, see [Junie CLI and JetBrains IDE integration](Junie-CLI-JetBrains-IDE-integration.md). | +| `/install-github-action` | Launch an interactive wizard for installing and configuring [Junie GitHub Action](Junie-on-GitHub.md) in the current GitHub repository. | +| `/import` | Import user- or project-level configs from other coding agents.

    Junie CLI detects and suggests import of guidelines, agent skills, slash commands, or MCP server configurations from other coding agents like Claude Code, Codex, or Cursor. | +| `/mcp` | Connect MCP servers to Junie CLI and manage the connections. | +| `/model` | Select the main Large Language Model (LLM) to be used by Junie CLI and, for supported models, the reasoning [effort level](Junie-CLI.md#model-and-effort).

    `Default` is the recommended pre-selected option with the best price quality ratio. The model behind the `Default` option is set dynamically and may change as new models are released. | +| `/new ` | Start another live session. If you provide ``, Junie opens the session with that text in the prompt. | +| `/plan ` | Toggle [plan mode](Junie-CLI-Plan-Mode.md). If you provide ``, Junie enables plan mode and submits the prompt immediately. | +| `/remote` | Open the current Junie CLI session in a web browser. For details, see [Remote Mode](Junie-CLI-Remote-Mode.md). | +| `/review` | Start a [local code review](Junie-CLI.md#local-code-review) of your changes (compared to `main`, the last commit, or unstaged changes) before you commit them. Requires a git repository. | +| `/settings` | Change Junie settings, including theme, notifications, step limit, subagents mode, and diff view mode. | +| `/quit` | Exit Junie CLI interactive mode while staying logged in. | +| `/title [name]` | Set the title of the current session. If you provide `[name]`, Junie uses it as the session title. If you omit it, Junie auto-generates a title by summarizing the whole conversation. A title you set this way persists across session reloads and is shown in `/history`, the terminal window title, and task-completion notifications, and it is not overwritten by the agent's automatic name. Alias: `/rename`. | +| `/update` | Check for updates and install if available. | +| `/usage` | See the cost breakdown for the current session, including token usage and used models. | +| `/worktree` | Open the worktree menu to create or switch to an isolated Git worktree for parallel file changes. See [Parallel sessions and worktrees](Junie-CLI-Worktrees.md). | +{width="800"} + +You can also add your own slash commands to Junie CLI. For details, see [Custom slash commands](Custom-slash-commands.md). + +## Navigation + +| Shortcut | Description | +|----------------|-------------------------------------------------------------------------| +| `Ctrl+C` twice | Quit Junie CLI interactive mode. | +| `!` | Run a shell command in the embedded terminal. Example: `!ls`. | +| `@` | Search for a file or folder in your project to attach it to the prompt. | +| `/` | Open the slash command suggestion menu. | +| `?` | Open the help menu to see all available shortcuts. | + + +## Modes and features + +| Shortcut | Description | +|-------------|-----------------------------------------------------------------------------------------------| +| `Shift+Tab` | Toggle between default mode and [plan mode](Junie-CLI-Plan-Mode.md). | +| `Ctrl+B` | Cycle through the [brave mode](Junie-CLI.md#brave-mode) levels (Off, Auto, On). | +| `Ctrl+R` | Search the prompt history. | +| `Ctrl+T` | Open subagent tasks. | +| `Ctrl+O` | Open the current main or selected subagent transcript using the configured transcript view. | + +## Text editing + +| Shortcut | Description | +|-----------------------------|---------------------------------------| +| `Shift+Enter` (or `Ctrl+J`) | Insert a new line in the prompt. | +| `Ctrl+A` | Move cursor to the start of the line. | +| `Ctrl+E` | Move cursor to the end of the line. | +| `Alt+B` | Move cursor one word backward. | +| `Alt+F` | Move cursor one word forward. | +| `Ctrl+U` | Delete the entire line. | +| `Ctrl+W` | Delete the word before the cursor. | diff --git a/junie/versions/2651.6/skills/junie-cli-docs/junie-cli-user-disk-storage.md b/junie/versions/2651.6/skills/junie-cli-docs/junie-cli-user-disk-storage.md new file mode 100644 index 0000000..9e90429 --- /dev/null +++ b/junie/versions/2651.6/skills/junie-cli-docs/junie-cli-user-disk-storage.md @@ -0,0 +1,169 @@ +# Junie CLI: What is stored on the user's disk + +This document describes what data the `junie` CLI stores on the user's disk, where it is stored, and what it is used for. + +## Base `junieHome` directory + +The main user directory for the CLI is `junieHome`. + +The path is resolved in this order: + +1. the `JUNIE_HOME` environment variable +2. the `junie.home` system property +3. the default directory `~/.junie` + +Examples: + +- macOS / Linux: `~/.junie` +- Windows: `%USERPROFILE%/.junie` + +## What is stored inside `junieHome` + +### `logs/` + +Directory for CLI logs. It is created when the application starts. + +### `settings.json` + +File with CLI user settings. + +At the moment, it stores values such as: + +- `braveMode` +- `modelForLaunch` +- `selectedTheme` +- `sessionCount` +- `junieId` +- `shareAnonymousStatistics` + +Format: JSON. + +### `sessions/` + +Directory with saved CLI sessions. + +Structure: + +- `sessions/index.jsonl` — session index, one JSON record per line +- `sessions//events.jsonl` — session event stream +- `sessions//state.json` — latest saved agent state +- `sessions///` — task-bound cache data +- `sessions///terminal-output/` — retained full stdout/stderr files for large terminal command output + +Notes: + +- some environment variables inside `state.json` and state events are encrypted through `EnvEncryptionService` +- the index and events are used to restore the history and state of interactive sessions +- terminal command output is buffered in memory and only written to a `terminal-output/` file once it grows past the + session event output cap (64 KB); smaller output is kept inline in the event stream and never creates a file. This means + small/internal commands (for example the local code review availability probe) leave no files behind, and internal + shell-state markers (which can include environment variables) are never written to disk for such output +- terminal output files are task-bound and referenced from terminal transcript events only when output is larger than the + session event output cap +- unreferenced generated terminal output files are cleaned up from the task folder when that task reaches a terminal state +- truncated terminal command results start with the corresponding retained `terminal-output/` file path so the agent can + inspect the full stdout/stderr when important details are outside the displayed output; the in-memory bounded view of + oversized output keeps its beginning and end with an explicit middle-truncation marker between them + +Format: + +- `index.jsonl` and `events.jsonl` — JSONL +- `state.json` — JSON +- `/terminal-output/` — text files + +### `misc/` + +Directory for small internal CLI files. + +Here, `junie` stores small internal files as separate key-based entries. + +#### `misc/config_hashes.json` + +Hashes of local custom skill configurations. + +Used to track new, updated, and problematic local skill file configurations. + +#### `misc/migration_state.json` + +Migration state for user and project settings imported from other products. + +Contains the list of already processed projects. + +### `secure_credentials.json` + +Fallback secret storage file. + +It is used only when system secure storage is unavailable: + +- macOS Keychain +- Windows Credential Manager +- Linux Secret Service + +If fallback storage is enabled, secrets are stored in this file as JSON. + +This is sensitive data. + +Project trust keys are never stored in this fallback file. Junie stores one random authentication key in native macOS Keychain, Windows Credential Manager, or Linux Secret Service, and falls back to an owner-only `trust/authentication-key` file when native secure storage is unavailable, locked, failing, or holds invalid key material. A trust selection is kept in memory for the current process only if even that file cannot be written. + +### `trust/` + +Directory containing one JSON marker per trusted exact-project or parent-directory scope. Marker filenames are SHA-256 hashes derived from the marker kind and canonical path. Marker contents include the version, marker kind, and canonical path plus an HMAC-SHA256 integrity code authenticated by the project trust key. The directory may also hold `authentication-key`, the owner-only fallback copy of that key used when native secure storage cannot hold it. + +Junie ignores malformed, renamed, symlinked, oversized, or incorrectly authenticated markers. Marker writes are atomic and use owner-only permissions on POSIX systems. Deleting an exact marker revokes that project; deleting a parent marker revokes inherited trust for its descendant projects on the next process launch. Choosing **Keep untrusted** does not write a marker. Separate markers also prevent one stale scope or concurrent Junie process from replacing unrelated trust decisions. + +Interactive UI launches always use these markers and prompt when no valid exact-project or ancestor marker exists, except for a verified linked git worktree of an already trusted project, which inherits that trust automatically without writing its own marker. Non-interactive JSON, ACP, and Gateway tasks are always trusted and do not consult these markers, because they cannot ask for a decision. The user home directory is never trusted: options that would trust it (directly or through a recursive parent scope containing it) are not offered and are refused by the resolver. + +### `mcp/mcp.json` + +User MCP server configuration. + +### `models/` + +Custom user model profiles. + +The CLI scans this directory for `*.json` files and loads model profiles from them. + +### `agent-skills/` + +User agent skills. + +The CLI reads skills from: + +- `/.junie/agent-skills` +- `/agent-skills` + +User files inside `junieHome` are stored in this directory. + +## What may be stored outside `junieHome` + +### `/.junie/mcp/mcp.json` + +Project-level MCP configuration. + +It belongs to a specific project rather than global user state. + +### `/.junie/models` + +Project-level custom model profiles. + +These take priority over user profiles from `/models`. + +## Short summary + +If you only look at the CLI's global user data, the main locations are: + +- `~/.junie/settings.json` +- `~/.junie/sessions/` +- `~/.junie/logs/` +- `~/.junie/trust/` +- `~/.junie/misc/` +- `~/.junie/mcp/mcp.json` +- `~/.junie/models/` +- `~/.junie/agent-skills/` +- `~/.junie/secure_credentials.json` — only if system secure storage is unavailable + +The most sensitive locations are: + +- `secure_credentials.json`, if fallback storage is used +- the contents of `sessions/`, because they may contain work history and agent state +- user model profiles in `models/`, if they contain keys or custom headers \ No newline at end of file diff --git a/kitty/kitty.conf b/kitty/kitty.conf new file mode 100644 index 0000000..2b4c0ba --- /dev/null +++ b/kitty/kitty.conf @@ -0,0 +1,91 @@ +# ---------- Appearance ---------- +include themes/Cyberpunk Scarlet Protocol Adjusted.conf + +font_family Menlo +font_size 13.0 +cursor_shape block +cursor_blink_interval 0.5 +copy_on_select yes + +# ---------- Background / visuals ---------- +background_opacity 0.98 +dynamic_background_opacity yes +window_padding_width 4 +inactive_text_alpha 0.85 +tab_bar_style powerline +tab_powerline_style slanted +tab_title_template "{fmt.fg.red}{bell_symbol}{activity_symbol}{fmt.fg.tab}{title}" + +# ---------- Scrollback / scrolling ---------- +scrollback_lines 200000 +wheel_scroll_multiplier 4.0 + +# ---------- Behavior ---------- +shell_integration enabled +# Use a widely available xterm terminfo instead of Kitty's default +# `xterm-kitty`, so remote SSH hosts, serial consoles, rescue shells, +# `vim`, `systemctl`, and other TUI tools work without installing Kitty +# terminfo everywhere. +term xterm-256color +enable_audio_bell no +confirm_os_window_close 1 +editor nvim + +# Keep Option available for macOS keyboard layouts that use it to type symbols +# such as `~`, `|`, and `\`. +macos_option_as_alt no +macos_quit_when_last_window_closed yes +macos_titlebar_color background + +# ---------- Apple-classic keybindings ---------- +# Tabs +map cmd+t new_tab +map cmd+w close_window +map cmd+1 goto_tab 1 +map cmd+2 goto_tab 2 +map cmd+3 goto_tab 3 +map cmd+4 goto_tab 4 +map cmd+5 goto_tab 5 +map cmd+6 goto_tab 6 +map cmd+7 goto_tab 7 +map cmd+8 goto_tab 8 +map cmd+9 goto_tab 9 + +# Prev/Next tab: on Swiss keyboards “[” and “]” are usually Option+5/6. +map cmd+[ previous_tab +map cmd+] next_tab +map cmd+alt+5 previous_tab +map cmd+alt+6 next_tab + +# Splits +map cmd+d launch --location=hsplit +# “\” is Option+Shift+7 on Swiss; bind BOTH. +map cmd+\ launch --location=vsplit +map cmd+shift+7 launch --location=vsplit + +# Focus between splits (Cmd+Alt+Arrows) +map cmd+alt+left neighboring_window left +map cmd+alt+right neighboring_window right +map cmd+alt+up neighboring_window up +map cmd+alt+down neighboring_window down + +# Fast movement in shells +# Option+Arrows: word-wise move (ESC b/f) +map alt+left send_text all \x1bb +map alt+right send_text all \x1bf +# Cmd+Left/Right: start/end of line (Ctrl-A/E) +map cmd+left send_text all \x01 +map cmd+right send_text all \x05 +# Cmd+Up/Down: send PageUp/PageDown CSI (works in less/vim/nvim/tmux) +map cmd+up send_text all \x1b[5~ +map cmd+down send_text all \x1b[6~ + +# Clipboard / app controls +# With `copy_on_select yes`, an active selection makes kitty treat ctrl+c as +# a copy action instead of SIGINT. Force ctrl+c to always send the interrupt. +map ctrl+c send_text all \x03 +map cmd+c copy_to_clipboard +map cmd+v paste_from_clipboard +map cmd+k clear_terminal scrollback active +map cmd+enter toggle_fullscreen +map cmd+, edit_config_file diff --git a/kitty/themes/Cyberpunk Scarlet Protocol Adjusted.conf b/kitty/themes/Cyberpunk Scarlet Protocol Adjusted.conf new file mode 100644 index 0000000..d3adcc1 --- /dev/null +++ b/kitty/themes/Cyberpunk Scarlet Protocol Adjusted.conf @@ -0,0 +1,26 @@ +# Cyberpunk Scarlet Protocol Adjusted +# Diff-balanced version with red/green contrast + +color0 #101116 +color1 #ff0051 +color2 #01dc84 +color3 #faf945 +color4 #0271b6 +color5 #c930c7 +color6 #00c5c7 +color7 #c7c7c7 +color8 #686868 +color9 #ff6e67 +color10 #60fa68 +color11 #fffc67 +color12 #6871ff +color13 #bd35ec +color14 #60fdff +color15 #ffffff + +background #101116 +foreground #e41951 +cursor #76ff9f +cursor_text_color #ffffff +selection_background #c1deff +selection_foreground #000000 diff --git a/packages/fedora/copr.txt b/packages/fedora/copr.txt deleted file mode 100644 index d7174a0..0000000 --- a/packages/fedora/copr.txt +++ /dev/null @@ -1,2 +0,0 @@ -atim:lazygit -zeno:scrcpy diff --git a/packages/macos/Brewfile.old b/packages/macos/Brewfile.old deleted file mode 100644 index dc2ac2c..0000000 --- a/packages/macos/Brewfile.old +++ /dev/null @@ -1,258 +0,0 @@ -tap "finestructure/tap" -tap "grishka/grishka" -tap "nikitabobko/tap" -# Cryptography and SSL/TLS Toolkit -brew "openssl@3" -# Swiss-army knife for Android testing and development -brew "adb-enhanced" -# Next-gen compiler infrastructure -brew "llvm" -# American Fuzzy Lop++ -brew "afl++" -# Core application library for C -brew "glib" -# Low-level library for pixel manipulation -brew "pixman" -# Tool for reverse engineering 3rd party, closed, binary Android apps -brew "apktool" -# Automatic configure script builder -brew "autoconf" -# Tool for generating GNU Standards-compliant Makefiles -brew "automake" -# Clone of cat(1) with syntax highlighting and Git integration -brew "bat" -# Backend processor for BibLaTeX -brew "biber" -# Object-file caching compiler wrapper -brew "ccache" -# Anti-virus software -brew "clamav" -# Formatting tools for C, C++, Obj-C, Java, JavaScript, TypeScript -brew "clang-format" -# Cross-platform make -brew "cmake" -# Documentation for CMake -brew "cmake-docs" -# GNU File, Shell, and Text utilities -brew "coreutils" -# Static analysis of C and C++ code -brew "cppcheck" -# Get a file from an HTTP, HTTPS or FTP server -brew "curl" -# USB programmer -brew "dfu-util" -# Load/unload environment variables based on $PWD -brew "direnv" -# .NET Core -brew "dotnet" -# Low-level access to audio, keyboard, mouse, joystick, and graphics -brew "sdl2" -# Play, record, convert, and stream select audio and video codecs -brew "ffmpeg" -# Command-line fuzzy finder written in Go -brew "fzf" -# GNU compiler collection -brew "gcc" -# Git extension for versioning large files -brew "git-lfs" -# Cryptographic library based on the code from GnuPG -brew "libgcrypt" -# X.509 and CMS library -brew "libksba" -# GNU Privacy Guard (OpenPGP) -brew "gnupg" -# Command-driven, interactive function plotting -brew "gnuplot" -# Open source programming language to build simple/reliable/efficient software -brew "go" -# Package compiler and linker metadata toolkit -brew "pkgconf" -# Generate introspection data for GObject libraries -brew "gobject-introspection" -# Open-source build automation tool based on the Groovy and Kotlin DSL -brew "gradle" -# Generic library support script -brew "libtool" -# Graph visualization software from AT&T and Bell Labs -brew "graphviz" -# GNU grep, egrep and fgrep -brew "grep" -# GNOME Python bindings (based on GObject Introspection) -brew "pygobject3" -# Development framework for multimedia applications -brew "gstreamer" -# C/C++ and Java libraries for Unicode and globalization -brew "icu4c@76" -# Cross-platform Java Version Manager -brew "jabba" -# Interpreted, interactive, object-oriented programming language -brew "python@3.13" -# Sane PBXProj files -brew "kin" -# Anti-bikeshedding Kotlin linter with built-in formatter -brew "ktlint" -# Simple terminal UI for git commands -brew "lazygit" -# Sophisticated file transfer program -brew "lftp" -# Postgres C API library -brew "libpq", link: true -# General purpose TCP-IP emulator -brew "libslirp" -# YAML Parser -brew "libyaml" -# LTeX+ Language Server: maintained fork of LTeX Language Server -brew "ltex-ls-plus" -# Utility for directing compilation -brew "make" -# Simple tool to make locally trusted development certificates -brew "mkcert" -# Message broker implementing the MQTT protocol -brew "mosquitto" -# General-purpose lossless data-compression library -brew "zlib" -# Open source relational database management system -brew "mysql-client" -# Ambitious Vim-fork focused on extensibility and agility -brew "neovim" -# Small build system for use with gyp or CMake -brew "ninja" -# Port scanning utility for large networks -brew "nmap" -# Open-source, cross-platform JavaScript runtime environment -brew "node" -# Libraries for security-enabled client and server applications -brew "nss" -# Manage multiple Node.js versions -brew "nvm" -# Create, run, and share large language models (LLMs) -brew "ollama" -# Cryptography and SSL/TLS Toolkit -brew "openssl@1.1" -# Draw UML diagrams -brew "plantuml" -# Your Gateway to Embedded Software Development Excellence -brew "platformio" -# Tool for managing OCI containers and pods -brew "podman" -# Alternative to docker-compose using podman -brew "podman-compose" -# Sound system for POSIX OSes -brew "pulseaudio" -# Python version management -brew "pyenv" -# Generic machine emulator and virtualizer -brew "qemu" -# Search tool like grep and The Silver Searcher -brew "ripgrep" -# Display and control your Android device -brew "scrcpy" -# 7-Zip is a file archiver with a high compression ratio -brew "sevenzip" -# Shell Script Compiler -brew "shc" -# Work with remote images registries -brew "skopeo" -# SOcket CAT: netcat on steroids -brew "socat" -# Audio processing library -brew "sound-touch" -# Tool to enforce Swift style and conventions -brew "swiftlint" -# Easiest, most secure way to use WireGuard and 2FA -brew "tailscale" -# User interface to the TELNET protocol -brew "telnet" -# Programmatically correct mistyped console commands -brew "thefuck" -# Display directories as trees (with optional color/HTML output) -brew "tree" -# Internet file retriever -brew "wget" -# JavaScript package manager -brew "yarn" -# Real-time type-ahead completion for Zsh -brew "zsh-autocomplete" -# Fish-like fast/unobtrusive autosuggestions for zsh -brew "zsh-autosuggestions" -# Fish shell like syntax highlighting for zsh -brew "zsh-syntax-highlighting" -# Describe your project -brew "finestructure/tap/arena" -# Android SDK component -cask "android-platform-tools" -# Electronics prototyping platform -cask "arduino-ide" -# Web security testing toolkit -cask "burp-suite" -# Visually compare and merge files -cask "diffmerge" -# Collaborative team software -cask "figma" -# Web browser -cask "firefox" -# 3D parametric modeller -cask "freecad" -# Web browser -cask "google-chrome" -# Terminal emulator as alternative to Apple's Terminal app -cask "iterm2" -# JetBrains tools manager -cask "jetbrains-toolbox" -# CAD application -cask "librecad" -# Software for Logitech devices -cask "logi-options+" -# Privacy-first, open-source platform for knowledge sharing and management -cask "logseq" -# Connect to your Android devices -cask "macdroid" -# Full TeX Live distribution with GUI applications -cask "mactex" -# Mesh processing system -cask "meshlab" -# Open source implementation of Microsoft's .NET Framework -cask "mono-mdk-for-visual-studio" -# Command-line tools for Nordic nRF Semiconductors -cask "nordic-nrf-command-line-tools" -# Knowledge base that works on top of a local folder of plain text Markdown files -cask "obsidian" -# Programmable solid 3D CAD modeller -cask "openscad" -# Collaboration platform for API development -cask "postman" -# Client for Proton Drive -cask "proton-drive" -# VPN client focusing on security -cask "protonvpn" -# HTTP debugging proxy -cask "proxyman" -# G-code generator for 3D printers (RepRap, Makerbot, Ultimaker etc.) -cask "prusaslicer" -# Imaging utility to install operating systems to a microSD card -cask "raspberry-pi-imager" -# Control your tools with a few keystrokes -cask "raycast" -# Software and Documentation pack for Segger J-Link debug probes -cask "segger-jlink" -# Team communication and collaboration software -cask "slack" -# Music streaming service -cask "spotify" -# LaTeX editor -cask "texifier" -# Virtual machines UI using QEMU -cask "utm" -# Multimedia player -cask "vlc" -# Binary releases of VS Code without MS branding/telemetry/licensing -cask "vscodium" -# Network protocol analyzer -cask "wireshark-app" -# Collect, organise, cite, and share research sources -cask "zotero" -vscode "eamodio.gitlens" -vscode "gicentre.markdown-preview-enhanced-with-litvis" -vscode "ltex-plus.vscode-ltex-plus" -vscode "ms-vscode.hexeditor" -vscode "waderyan.gitblame" diff --git a/packages/macos/Brewfile.old.20260331072104 b/packages/macos/Brewfile.old.20260331072104 deleted file mode 100644 index 6663fe0..0000000 --- a/packages/macos/Brewfile.old.20260331072104 +++ /dev/null @@ -1,368 +0,0 @@ -tap "finestructure/tap" -tap "grishka/grishka" -tap "nikitabobko/tap" -# Cryptography and SSL/TLS Toolkit -brew "openssl@3" -# Swiss-army knife for Android testing and development -brew "adb-enhanced" -# Next-gen compiler infrastructure -brew "llvm" -# American Fuzzy Lop++ -brew "afl++" -# Core application library for C -brew "glib" -# Low-level library for pixel manipulation -brew "pixman" -# Tool for reverse engineering 3rd party, closed, binary Android apps -brew "apktool" -# Automatic configure script builder -brew "autoconf" -# Tool for generating GNU Standards-compliant Makefiles -brew "automake" -# Clone of cat(1) with syntax highlighting and Git integration -brew "bat" -# Backend processor for BibLaTeX -brew "biber" -# Object-file caching compiler wrapper -brew "ccache" -# Anti-virus software -brew "clamav" -# Formatting tools for C, C++, Obj-C, Java, JavaScript, TypeScript -brew "clang-format" -# Cross-platform make -brew "cmake" -# Documentation for CMake -brew "cmake-docs" -# GNU File, Shell, and Text utilities -brew "coreutils" -# Static analysis of C and C++ code -brew "cppcheck" -# Get a file from an HTTP, HTTPS or FTP server -brew "curl" -# USB programmer -brew "dfu-util" -# Load/unload environment variables based on $PWD -brew "direnv" -# .NET Core -brew "dotnet" -# Low-level access to audio, keyboard, mouse, joystick, and graphics -brew "sdl2" -# Play, record, convert, and stream select audio and video codecs -brew "ffmpeg" -# Command-line fuzzy finder written in Go -brew "fzf" -# GNU compiler collection -brew "gcc" -# Git extension for versioning large files -brew "git-lfs" -# Cryptographic library based on the code from GnuPG -brew "libgcrypt" -# X.509 and CMS library -brew "libksba" -# GNU Privacy Guard (OpenPGP) -brew "gnupg" -# Command-driven, interactive function plotting -brew "gnuplot" -# Open source programming language to build simple/reliable/efficient software -brew "go" -# Package compiler and linker metadata toolkit -brew "pkgconf" -# Generate introspection data for GObject libraries -brew "gobject-introspection" -# Open-source build automation tool based on the Groovy and Kotlin DSL -brew "gradle" -# Generic library support script -brew "libtool" -# Graph visualization software from AT&T and Bell Labs -brew "graphviz" -# GNU grep, egrep and fgrep -brew "grep" -# GNOME Python bindings (based on GObject Introspection) -brew "pygobject3" -# Development framework for multimedia applications -brew "gstreamer" -# C/C++ and Java libraries for Unicode and globalization -brew "icu4c@76" -# Cross-platform Java Version Manager -brew "jabba" -# Interpreted, interactive, object-oriented programming language -brew "python@3.13" -# Sane PBXProj files -brew "kin" -# Anti-bikeshedding Kotlin linter with built-in formatter -brew "ktlint" -# Simple terminal UI for git commands -brew "lazygit" -# Sophisticated file transfer program -brew "lftp" -# Postgres C API library -brew "libpq", link: true -# General purpose TCP-IP emulator -brew "libslirp" -# YAML Parser -brew "libyaml" -# LTeX+ Language Server: maintained fork of LTeX Language Server -brew "ltex-ls-plus" -# Utility for directing compilation -brew "make" -# Simple tool to make locally trusted development certificates -brew "mkcert" -# Message broker implementing the MQTT protocol -brew "mosquitto" -# General-purpose lossless data-compression library -brew "zlib" -# Open source relational database management system -brew "mysql-client" -# Ambitious Vim-fork focused on extensibility and agility -brew "neovim" -# Small build system for use with gyp or CMake -brew "ninja" -# Port scanning utility for large networks -brew "nmap" -# Open-source, cross-platform JavaScript runtime environment -brew "node" -# Libraries for security-enabled client and server applications -brew "nss" -# Manage multiple Node.js versions -brew "nvm" -# Create, run, and share large language models (LLMs) -brew "ollama" -# Cryptography and SSL/TLS Toolkit -brew "openssl@1.1" -# Draw UML diagrams -brew "plantuml" -# Your Gateway to Embedded Software Development Excellence -brew "platformio" -# Tool for managing OCI containers and pods -brew "podman" -# Alternative to docker-compose using podman -brew "podman-compose" -# Sound system for POSIX OSes -brew "pulseaudio" -# Python version management -brew "pyenv" -# Generic machine emulator and virtualizer -brew "qemu" -# Search tool like grep and The Silver Searcher -brew "ripgrep" -# Display and control your Android device -brew "scrcpy" -# 7-Zip is a file archiver with a high compression ratio -brew "sevenzip" -# Shell Script Compiler -brew "shc" -# Work with remote images registries -brew "skopeo" -# SOcket CAT: netcat on steroids -brew "socat" -# Audio processing library -brew "sound-touch" -# Tool to enforce Swift style and conventions -brew "swiftlint" -# Easiest, most secure way to use WireGuard and 2FA -brew "tailscale" -# User interface to the TELNET protocol -brew "telnet" -# Programmatically correct mistyped console commands -brew "thefuck" -# Display directories as trees (with optional color/HTML output) -brew "tree" -# Internet file retriever -brew "wget" -# JavaScript package manager -brew "yarn" -# Real-time type-ahead completion for Zsh -brew "zsh-autocomplete" -# Fish-like fast/unobtrusive autosuggestions for zsh -brew "zsh-autosuggestions" -# Fish shell like syntax highlighting for zsh -brew "zsh-syntax-highlighting" -# Describe your project -brew "finestructure/tap/arena" -# Android SDK component -cask "android-platform-tools" -# Electronics prototyping platform -cask "arduino-ide" -# Web security testing toolkit -cask "burp-suite" -# Visually compare and merge files -cask "diffmerge" -# Collaborative team software -cask "figma" -# Web browser -cask "firefox" -# 3D parametric modeller -cask "freecad" -# Web browser -cask "google-chrome" -# Terminal emulator as alternative to Apple's Terminal app -cask "iterm2" -# JetBrains tools manager -cask "jetbrains-toolbox" -# CAD application -cask "librecad" -# Software for Logitech devices -cask "logi-options+" -# Privacy-first, open-source platform for knowledge sharing and management -cask "logseq" -# Connect to your Android devices -cask "macdroid" -# Full TeX Live distribution with GUI applications -cask "mactex" -# Mesh processing system -cask "meshlab" -# Open source implementation of Microsoft's .NET Framework -cask "mono-mdk-for-visual-studio" -# Command-line tools for Nordic nRF Semiconductors -cask "nordic-nrf-command-line-tools" -# Knowledge base that works on top of a local folder of plain text Markdown files -cask "obsidian" -# Programmable solid 3D CAD modeller -cask "openscad" -# Collaboration platform for API development -cask "postman" -# Client for Proton Drive -cask "proton-drive" -# VPN client focusing on security -cask "protonvpn" -# HTTP debugging proxy -cask "proxyman" -# G-code generator for 3D printers (RepRap, Makerbot, Ultimaker etc.) -cask "prusaslicer" -# Imaging utility to install operating systems to a microSD card -cask "raspberry-pi-imager" -# Control your tools with a few keystrokes -cask "raycast" -# Software and Documentation pack for Segger J-Link debug probes -cask "segger-jlink" -# Team communication and collaboration software -cask "slack" -# Music streaming service -cask "spotify" -# LaTeX editor -cask "texifier" -# Virtual machines UI using QEMU -cask "utm" -# Multimedia player -cask "vlc" -# Binary releases of VS Code without MS branding/telemetry/licensing -cask "vscodium" -# Network protocol analyzer -cask "wireshark-app" -# Collect, organise, cite, and share research sources -cask "zotero" -vscode "13xforever.language-x86-64-assembly" -vscode "aaron-bond.better-comments" -vscode "alefragnani.bookmarks" -vscode "alexcvzz.vscode-sqlite" -vscode "angular.ng-template" -vscode "anilkumarum.compile-ts" -vscode "anweber.httpbook" -vscode "anweber.vscode-httpyac" -vscode "bbenoist.doxygen" -vscode "bierner.emojisense" -vscode "bleastprogram.cpp-compiler" -vscode "cheshirekow.cmake-format" -vscode "christian-kohler.npm-intellisense" -vscode "christian-kohler.path-intellisense" -vscode "cschlosser.doxdocgen" -vscode "davidanson.vscode-markdownlint" -vscode "dbaeumer.vscode-eslint" -vscode "ddorch.codium-devcontainer" -vscode "devsense.composer-php-vscode" -vscode "devsense.intelli-php-vscode" -vscode "devsense.phptools-vscode" -vscode "devsense.profiler-php-vscode" -vscode "dreamcatcher45.podmanager" -vscode "dsznajder.es7-react-js-snippets" -vscode "eamodio.gitlens" -vscode "eclipse-cdt.serial-monitor" -vscode "efoerster.texlab" -vscode "ericsia.pythonsnippets3" -vscode "esbenp.prettier-vscode" -vscode "espressif.esp-idf-extension" -vscode "firefox-devtools.vscode-firefox-debug" -vscode "formulahendry.code-runner" -vscode "foxundermoon.shell-format" -vscode "franneck94.c-cpp-runner" -vscode "franneck94.vscode-c-cpp-config" -vscode "franneck94.vscode-c-cpp-dev-extension-pack" -vscode "franneck94.vscode-typescript-extension-pack" -vscode "fwcd.kotlin" -vscode "gicentre.markdown-preview-enhanced-with-litvis" -vscode "gruntfuggly.todo-tree" -vscode "guyutongxue.cpp-reference" -vscode "gydunhn.javascript-essentials" -vscode "gydunhn.typescript-essentials" -vscode "gydunhn.vsc-essentials-core" -vscode "ibm.output-colorizer" -vscode "james-yu.latex-workshop" -vscode "jbenden.c-cpp-flylint" -vscode "jebbs.plantuml" -vscode "jeff-hykin.better-cpp-syntax" -vscode "jeff-hykin.better-shellscript-syntax" -vscode "jeffersonqin.latex-snippets-jeff" -vscode "jock.svg" -vscode "kotlin-darcula-syntax.kotlin-darcula-syntax" -vscode "llvm-vs-code-extensions.vscode-clangd" -vscode "ltex-plus.vscode-ltex-plus" -vscode "mads-hartmann.bash-ide-vscode" -vscode "magicstack.magicpython" -vscode "marus25.cortex-debug" -vscode "mathiasfrohlich.kotlin" -vscode "mattpocock.ts-error-translator" -vscode "mcu-debug.debug-tracker-vscode" -vscode "mcu-debug.memory-view" -vscode "mcu-debug.peripheral-viewer" -vscode "mcu-debug.rtos-views" -vscode "mjpvs.latex-previewer" -vscode "mkhl.direnv" -vscode "ms-azuretools.vscode-containers" -vscode "ms-azuretools.vscode-docker" -vscode "ms-python.debugpy" -vscode "ms-python.python" -vscode "ms-python.vscode-python-envs" -vscode "ms-vscode.cmake-tools" -vscode "ms-vscode.hexeditor" -vscode "ms-vscode.vscode-typescript-next" -vscode "mtxr.sqltools" -vscode "mtxr.sqltools-driver-sqlite" -vscode "oderwat.indent-rainbow" -vscode "phil294.git-log--graph" -vscode "philosowaffle.openapi-designer" -vscode "pinage404.bash-extension-pack" -vscode "pokey.parse-tree" -vscode "postman.postman-for-vscode" -vscode "prisma.prisma-insider" -vscode "project-accelerate.shared-state-store" -vscode "qwtel.sqlite-viewer" -vscode "rail5.bashpp" -vscode "redhat.java" -vscode "redhat.vscode-xml" -vscode "redocly.openapi-vs-code" -vscode "rintoj.json-organizer" -vscode "rogalmic.bash-debug" -vscode "rpinski.shebang-snippets" -vscode "shd101wyy.markdown-preview-enhanced" -vscode "shopify.ruby-lsp" -vscode "sndst00m.vscode-native-svg-preview" -vscode "sr-team.clang-tidy-sr-team-fork" -vscode "sr-team.vscode-clangd-cmake" -vscode "sr-team.vscode-cpp-file-renamer" -vscode "sswg.swift-lang" -vscode "swiftstream.swiftstream" -vscode "tecosaur.latex-utilities" -vscode "timonwong.shellcheck" -vscode "tombonnike.vscode-status-bar-format-toggle" -vscode "tomi.xajssnippets" -vscode "tomi.xasnippets" -vscode "torn4dom4n.latex-support" -vscode "twxs.cmake" -vscode "usernamehw.errorlens" -vscode "vadimcn.vscode-lldb" -vscode "vknabel.vscode-apple-swift-format" -vscode "vknabel.vscode-swiftformat" -vscode "waderyan.gitblame" -vscode "xabikos.javascriptsnippets" -vscode "yoavbls.pretty-ts-errors" -vscode "yzhang.markdown-all-in-one" diff --git a/packages/macos/Brewfile.old.20260615082215 b/packages/macos/Brewfile.old.20260615082215 deleted file mode 100644 index 72375ae..0000000 --- a/packages/macos/Brewfile.old.20260615082215 +++ /dev/null @@ -1,395 +0,0 @@ -tap "finestructure/tap" -tap "grishka/grishka" -tap "homebrew-ffmpeg/ffmpeg" -tap "nikitabobko/tap" -# Cryptography and SSL/TLS Toolkit -brew "openssl@3" -# Swiss-army knife for Android testing and development -brew "adb-enhanced" -# Next-gen compiler infrastructure -brew "llvm" -# American Fuzzy Lop++ -brew "afl++" -# Core application library for C -brew "glib" -# Low-level library for pixel manipulation -brew "pixman" -# Tool for reverse engineering 3rd party, closed, binary Android apps -brew "apktool" -# Automatic configure script builder -brew "autoconf" -# Tool for generating GNU Standards-compliant Makefiles -brew "automake" -# Clone of cat(1) with syntax highlighting and Git integration -brew "bat" -# Backend processor for BibLaTeX -brew "biber" -# Object-file caching compiler wrapper -brew "ccache" -# Anti-virus software -brew "clamav" -# Formatting tools for C, C++, Obj-C, Java, JavaScript, TypeScript -brew "clang-format" -# Cross-platform make -brew "cmake" -# Documentation for CMake -brew "cmake-docs" -# GNU File, Shell, and Text utilities -brew "coreutils" -# Static analysis of C and C++ code -brew "cppcheck" -# Get a file from an HTTP, HTTPS or FTP server -brew "curl" -# Library for USB device access -brew "libusb" -# USB programmer -brew "dfu-util" -# Load/unload environment variables based on $PWD -brew "direnv" -# .NET Core -brew "dotnet" -# Command-line fuzzy finder written in Go -brew "fzf" -# GNU compiler collection -brew "gcc" -# Git extension for versioning large files -brew "git-lfs" -# Cryptographic library based on the code from GnuPG -brew "libgcrypt" -# X.509 and CMS library -brew "libksba" -# GNU Privacy Guard (OpenPGP) -brew "gnupg" -# Command-driven, interactive function plotting -brew "gnuplot" -# Open source programming language to build simple/reliable/efficient software -brew "go" -# Package compiler and linker metadata toolkit -brew "pkgconf" -# Generate introspection data for GObject libraries -brew "gobject-introspection" -# Open-source build automation tool based on the Groovy and Kotlin DSL -brew "gradle" -# Generic library support script -brew "libtool" -# Graph visualization software from AT&T and Bell Labs -brew "graphviz" -# GNU grep, egrep and fgrep -brew "grep" -# Low-level access to audio, keyboard, mouse, joystick, and graphics -brew "sdl2" -# Play, record, convert, and stream select audio and video codecs -brew "ffmpeg", args: ["with-webp", "with-xvid"] -# GNOME Python bindings (based on GObject Introspection) -brew "pygobject3" -# Development framework for multimedia applications -brew "gstreamer" -# C/C++ and Java libraries for Unicode and globalization -brew "icu4c@76" -# Tools and libraries to manipulate images in select formats -brew "imagemagick" -# Cross-platform Java Version Manager -brew "jabba" -# Interpreted, interactive, object-oriented programming language -brew "python@3.13" -# Sane PBXProj files -brew "kin" -# Anti-bikeshedding Kotlin linter with built-in formatter -brew "ktlint" -# Simple terminal UI for git commands -brew "lazygit" -# Sophisticated file transfer program -brew "lftp" -# Postgres C API library -brew "libpq", link: true -# General purpose TCP-IP emulator -brew "libslirp" -# YAML Parser -brew "libyaml" -# LTeX+ Language Server: maintained fork of LTeX Language Server -brew "ltex-ls-plus" -# Utility for directing compilation -brew "make" -# Simple tool to make locally trusted development certificates -brew "mkcert" -# Message broker implementing the MQTT protocol -brew "mosquitto" -# General-purpose lossless data-compression library -brew "zlib" -# Open source relational database management system -brew "mysql-client" -# Ambitious Vim-fork focused on extensibility and agility -brew "neovim" -# Small build system for use with gyp or CMake -brew "ninja" -# Port scanning utility for large networks -brew "nmap" -# Open-source, cross-platform JavaScript runtime environment -brew "node" -# Libraries for security-enabled client and server applications -brew "nss" -# Manage multiple Node.js versions -brew "nvm" -# Create, run, and share large language models (LLMs) -brew "ollama" -# Development kit for the Java programming language -brew "openjdk@21" -# Cryptography and SSL/TLS Toolkit -brew "openssl@1.1" -# Draw UML diagrams -brew "plantuml" -# Generate podman quadlet files from a podman command or compose file -brew "podlet" -# Tool for managing OCI containers and pods -brew "podman" -# Alternative to docker-compose using podman -brew "podman-compose" -# Sound system for POSIX OSes -brew "pulseaudio" -# Python version management -brew "pyenv" -# Generic machine emulator and virtualizer -brew "qemu" -# Search tool like grep and The Silver Searcher -brew "ripgrep" -# Display and control your Android device -brew "scrcpy" -# 7-Zip is a file archiver with a high compression ratio -brew "sevenzip" -# Shell Script Compiler -brew "shc" -# Work with remote images registries -brew "skopeo" -# SOcket CAT: netcat on steroids -brew "socat" -# Audio processing library -brew "sound-touch" -# Tool to enforce Swift style and conventions -brew "swiftlint" -# Easiest, most secure way to use WireGuard and 2FA -brew "tailscale" -# User interface to the TELNET protocol -brew "telnet" -# Programmatically correct mistyped console commands -brew "thefuck" -# Display directories as trees (with optional color/HTML output) -brew "tree" -# Internet file retriever -brew "wget" -# JavaScript package manager -brew "yarn" -# Real-time type-ahead completion for Zsh -brew "zsh-autocomplete" -# Fish-like fast/unobtrusive autosuggestions for zsh -brew "zsh-autosuggestions" -# Fish shell like syntax highlighting for zsh -brew "zsh-syntax-highlighting" -# Describe your project -brew "finestructure/tap/arena" -# Play, record, convert, and stream audio and video -brew "homebrew-ffmpeg/ffmpeg/ffmpeg", args: ["with-webp", "with-xvid"] -# Android SDK component -cask "android-platform-tools" -# Network scanner -cask "angry-ip-scanner" -# Electronics prototyping platform -cask "arduino-ide" -# Utility improving 3rd party mouse performance and functionalities -cask "bettermouse" -# Web security testing toolkit -cask "burp-suite" -# Visually compare and merge files -cask "diffmerge" -# Collaborative team software -cask "figma" -# Web browser -cask "firefox" -# 3D parametric modeller -cask "freecad" -# Web browser -cask "google-chrome" -# Hex editor for reverse engineers -cask "imhex" -# Terminal emulator as alternative to Apple's Terminal app -cask "iterm2" -# JetBrains tools manager -cask "jetbrains-toolbox" -# CAD application -cask "librecad" -# Privacy-first, open-source platform for knowledge sharing and management -cask "logseq" -# Connect to your Android devices -cask "macdroid" -# Full TeX Live distribution with GUI applications -cask "mactex" -# Mesh processing system -cask "meshlab" -# Open source implementation of Microsoft's .NET Framework -cask "mono-mdk-for-visual-studio" -cask "mqtt-explorer" -# Desktop sync client for Nextcloud software products -cask "nextcloud-vfs" -# Command-line tools for Nordic nRF Semiconductors -cask "nordic-nrf-command-line-tools" -# Knowledge base that works on top of a local folder of plain text Markdown files -cask "obsidian" -# Programmable solid 3D CAD modeller -cask "openscad" -# Collaboration platform for API development -cask "postman" -# Client for Proton Drive -cask "proton-drive" -# VPN client focusing on security -cask "protonvpn" -# HTTP debugging proxy -cask "proxyman" -# G-code generator for 3D printers (RepRap, Makerbot, Ultimaker etc.) -cask "prusaslicer" -# Imaging utility to install operating systems to a microSD card -cask "raspberry-pi-imager" -# Control your tools with a few keystrokes -cask "raycast" -# Software and Documentation pack for Segger J-Link debug probes -cask "segger-jlink" -# Team communication and collaboration software -cask "slack" -# Music streaming service -cask "spotify" -# Mesh VPN based on WireGuard -cask "tailscale-app" -# JDK from the Eclipse Foundation (Adoptium) -cask "temurin@8" -# LaTeX editor -cask "texifier" -# Customizable email client -cask "thunderbird" -# Virtual machines UI using QEMU -cask "utm" -# Multimedia player -cask "vlc" -# Binary releases of VS Code without MS branding/telemetry/licensing -cask "vscodium" -# Network protocol analyzer -cask "wireshark-app" -# Collect, organise, cite, and share research sources -cask "zotero" -vscode "13xforever.language-x86-64-assembly" -vscode "aaron-bond.better-comments" -vscode "alefragnani.bookmarks" -vscode "alexcvzz.vscode-sqlite" -vscode "angular.ng-template" -vscode "anilkumarum.compile-ts" -vscode "anweber.httpbook" -vscode "anweber.vscode-httpyac" -vscode "bbenoist.doxygen" -vscode "bierner.emojisense" -vscode "bleastprogram.cpp-compiler" -vscode "cheshirekow.cmake-format" -vscode "christian-kohler.npm-intellisense" -vscode "christian-kohler.path-intellisense" -vscode "continue.continue" -vscode "cschlosser.doxdocgen" -vscode "davidanson.vscode-markdownlint" -vscode "dbaeumer.vscode-eslint" -vscode "ddorch.codium-devcontainer" -vscode "devsense.composer-php-vscode" -vscode "devsense.intelli-php-vscode" -vscode "devsense.phptools-vscode" -vscode "devsense.profiler-php-vscode" -vscode "dreamcatcher45.podmanager" -vscode "dsznajder.es7-react-js-snippets" -vscode "eamodio.gitlens" -vscode "eclipse-cdt.serial-monitor" -vscode "efoerster.texlab" -vscode "ericsia.pythonsnippets3" -vscode "esbenp.prettier-vscode" -vscode "espressif.esp-idf-extension" -vscode "firefox-devtools.vscode-firefox-debug" -vscode "formulahendry.code-runner" -vscode "foxundermoon.shell-format" -vscode "franneck94.c-cpp-runner" -vscode "franneck94.vscode-c-cpp-config" -vscode "franneck94.vscode-c-cpp-dev-extension-pack" -vscode "franneck94.vscode-typescript-extension-pack" -vscode "fwcd.kotlin" -vscode "gicentre.markdown-preview-enhanced-with-litvis" -vscode "gruntfuggly.todo-tree" -vscode "guyutongxue.cpp-reference" -vscode "gydunhn.javascript-essentials" -vscode "gydunhn.typescript-essentials" -vscode "gydunhn.vsc-essentials-core" -vscode "hangxingliu.vscode-systemd-support" -vscode "ibm.output-colorizer" -vscode "james-yu.latex-workshop" -vscode "jbenden.c-cpp-flylint" -vscode "jeanp413.open-remote-ssh" -vscode "jebbs.plantuml" -vscode "jeff-hykin.better-cpp-syntax" -vscode "jeff-hykin.better-shellscript-syntax" -vscode "jeffersonqin.latex-snippets-jeff" -vscode "jock.svg" -vscode "kotlin-darcula-syntax.kotlin-darcula-syntax" -vscode "llvm-vs-code-extensions.lldb-dap" -vscode "llvm-vs-code-extensions.vscode-clangd" -vscode "lordimmaculate.platformio-ide" -vscode "ltex-plus.vscode-ltex-plus" -vscode "mads-hartmann.bash-ide-vscode" -vscode "magicstack.magicpython" -vscode "marus25.cortex-debug" -vscode "mathiasfrohlich.kotlin" -vscode "mattpocock.ts-error-translator" -vscode "mcu-debug.debug-tracker-vscode" -vscode "mcu-debug.memory-view" -vscode "mcu-debug.peripheral-viewer" -vscode "mcu-debug.rtos-views" -vscode "mjpvs.latex-previewer" -vscode "mkhl.direnv" -vscode "ms-azuretools.vscode-containers" -vscode "ms-azuretools.vscode-docker" -vscode "ms-python.debugpy" -vscode "ms-python.python" -vscode "ms-python.vscode-python-envs" -vscode "ms-vscode.cmake-tools" -vscode "ms-vscode.hexeditor" -vscode "ms-vscode.vscode-typescript-next" -vscode "mtxr.sqltools" -vscode "mtxr.sqltools-driver-sqlite" -vscode "oderwat.indent-rainbow" -vscode "phil294.git-log--graph" -vscode "philosowaffle.openapi-designer" -vscode "pinage404.bash-extension-pack" -vscode "pokey.parse-tree" -vscode "postman.postman-for-vscode" -vscode "prisma.prisma-insider" -vscode "project-accelerate.shared-state-store" -vscode "rail5.bashpp" -vscode "redhat.java" -vscode "redhat.vscode-xml" -vscode "redocly.openapi-vs-code" -vscode "repreng.csv" -vscode "rintoj.json-organizer" -vscode "rogalmic.bash-debug" -vscode "rpinski.shebang-snippets" -vscode "shd101wyy.markdown-preview-enhanced" -vscode "shopify.ruby-lsp" -vscode "sndst00m.vscode-native-svg-preview" -vscode "sr-team.clang-tidy-sr-team-fork" -vscode "sr-team.vscode-clangd-cmake" -vscode "sr-team.vscode-cpp-file-renamer" -vscode "swiftlang.swift-vscode" -vscode "swiftstream.swiftstream" -vscode "tecosaur.latex-utilities" -vscode "timonwong.shellcheck" -vscode "tombonnike.vscode-status-bar-format-toggle" -vscode "tomi.xajssnippets" -vscode "tomi.xasnippets" -vscode "torn4dom4n.latex-support" -vscode "twxs.cmake" -vscode "usernamehw.errorlens" -vscode "vadimcn.vscode-lldb" -vscode "vknabel.vscode-apple-swift-format" -vscode "vknabel.vscode-swiftformat" -vscode "waderyan.gitblame" -vscode "xabikos.javascriptsnippets" -vscode "yoavbls.pretty-ts-errors" -vscode "yzhang.markdown-all-in-one" diff --git a/packages/manjaro/external/10-jetbrains-toolbox.sh b/packages/manjaro/external/10-jetbrains-toolbox.sh deleted file mode 100644 index 25b7ea5..0000000 --- a/packages/manjaro/external/10-jetbrains-toolbox.sh +++ /dev/null @@ -1,18 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -version="3.0.1.59888" -base_dir="$HOME/.config/jetbrains" -archive="$base_dir/jetbrains-toolbox-$version.tar.gz" -unpacked="$base_dir/jetbrains-toolbox-$version" -bin="$unpacked/bin/jetbrains-toolbox" - -mkdir -p "$base_dir" - -if [[ ! -x "$bin" ]]; then - echo "Installing JetBrains Toolbox..." - wget -O "$archive" "https://download.jetbrains.com/toolbox/jetbrains-toolbox-$version.tar.gz" - tar -xzf "$archive" -C "$base_dir" -fi - -nohup "$bin" >/dev/null 2>&1 & \ No newline at end of file diff --git a/packages/manjaro/external/20-jabba.sh b/packages/manjaro/external/20-jabba.sh deleted file mode 100644 index 567705b..0000000 --- a/packages/manjaro/external/20-jabba.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -if [[ ! -d "$HOME/.jabba" ]]; then - echo "Installing jabba..." - curl -fsSL https://github.com/shyiko/jabba/raw/master/install.sh | bash -fi \ No newline at end of file diff --git a/packages/manjaro/external/30-joplin.sh b/packages/manjaro/external/30-joplin.sh deleted file mode 100644 index 095d1e5..0000000 --- a/packages/manjaro/external/30-joplin.sh +++ /dev/null @@ -1,7 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -if ! command -v joplin >/dev/null 2>&1; then - echo "Installing Joplin..." - wget -O - https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh | bash -fi \ No newline at end of file diff --git a/packages/manjaro/external/40-cisco-note.sh b/packages/manjaro/external/40-cisco-note.sh deleted file mode 100644 index 98ed81e..0000000 --- a/packages/manjaro/external/40-cisco-note.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -echo "Manual install required for Cisco Secure Client:" -echo " https://servicedesk.zhaw.ch/tas/public/ssp/content/search?q=KI%201747" \ No newline at end of file diff --git a/packages/manjaro/external/50-celeste-note.sh b/packages/manjaro/external/50-celeste-note.sh deleted file mode 100644 index d2a6169..0000000 --- a/packages/manjaro/external/50-celeste-note.sh +++ /dev/null @@ -1,5 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -echo "Celeste can be installed from:" -echo " https://github.com/hwittenborn/celeste" \ No newline at end of file diff --git a/setup.atomic-fedora.sh b/setup.atomic-fedora.sh deleted file mode 100644 index da46c33..0000000 --- a/setup.atomic-fedora.sh +++ /dev/null @@ -1,220 +0,0 @@ -#!/usr/bin/env bash - -# Package manifests: -# packages/fedora-atomic/rpm-ostree.txt -# packages/fedora-atomic/flatpak.txt -# packages/fedora-atomic/toolboxes.txt -# packages/fedora-atomic/toolboxes/*.txt -# -# Export current Flatpaks: -# flatpak list --app --columns=application | sort > packages/fedora-atomic/flatpak.txt -# -# Export toolbox package lists: -# toolbox run cpp-dev bash -lc 'dnf repoquery --userinstalled --qf "%{name}\n" | sort' -# toolbox run latex bash -lc 'dnf repoquery --userinstalled --qf "%{name}\n" | sort' -# toolbox run mobile bash -lc 'dnf repoquery --userinstalled --qf "%{name}\n" | sort' -# toolbox run cli-dev bash -lc 'dnf repoquery --userinstalled --qf "%{name}\n" | sort' - -set -euo pipefail - -REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PKG_DIR="$REPO_DIR/packages/fedora-atomic" - -log() { - printf '%s\n' "$*" -} - -require_atomic_fedora() { - if [[ ! -f /etc/fedora-release ]]; then - log "error: this script is for Fedora" - exit 1 - fi - - if ! command -v rpm-ostree >/dev/null 2>&1; then - log "error: rpm-ostree not found; this does not look like Fedora Atomic" - exit 1 - fi - - if [[ $EUID -eq 0 ]]; then - log "error: run as a regular user, not root" - exit 1 - fi -} - -read_manifest() { - local file="$1" - [[ -f "$file" ]] || return 0 - grep -vE '^\s*$|^\s*#' "$file" -} - -layer_host_packages() { - local file="$PKG_DIR/rpm-ostree.txt" - mapfile -t packages < <(read_manifest "$file") - - if [[ ${#packages[@]} -eq 0 ]]; then - log "No host packages to layer." - return 0 - fi - - log "Layering host packages with rpm-ostree..." - sudo rpm-ostree install "${packages[@]}" - log "Host package layering complete. Reboot required to use newly layered packages." -} - -setup_default_shell() { - if [[ "$(basename "${SHELL}")" != "zsh" ]]; then - log "Changing default shell to zsh..." - chsh -s "$(command -v zsh)" - log "Shell changed. Log out/in or reboot for it to take effect." - fi -} - -install_zsh_plugins() { - log "Installing zsh plugins..." - mkdir -p "$HOME/.zsh" - - [[ -d "$HOME/.zsh/zsh-autosuggestions" ]] || \ - git clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" - - [[ -d "$HOME/.zsh/zsh-syntax-highlighting" ]] || \ - git clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" - - [[ -d "$HOME/.zsh/zsh-autocomplete" ]] || \ - git clone --depth 1 https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" -} - -setup_tealdeer_and_vim() { - mkdir -p "$HOME/.config/tealdeer" - tldr --update || true - mkdir -p "$HOME/.vim/undo" -} - -setup_flatpak() { - log "Ensuring Flatpak + Flathub..." - sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo || true - flatpak update -y || true - - local file="$PKG_DIR/flatpak.txt" - while IFS= read -r pkg; do - [[ -z "$pkg" ]] && continue - log "Installing Flatpak: $pkg" - flatpak install -y flathub "$pkg" || log "warn: failed/skipped flatpak $pkg" - done < <(read_manifest "$file") -} - -tb_run() { - local name="$1" - shift - toolbox run --container "$name" bash -lc "$*" -} - -create_toolboxes() { - local file="$PKG_DIR/toolboxes.txt" - while IFS= read -r box; do - [[ -z "$box" ]] && continue - toolbox create --container "$box" || true - done < <(read_manifest "$file") -} - -install_toolbox_packages() { - local toolbox="$1" - local manifest="$PKG_DIR/toolboxes/$toolbox.txt" - - [[ -f "$manifest" ]] || return 0 - - mapfile -t packages < <(read_manifest "$manifest") - [[ ${#packages[@]} -gt 0 ]] || return 0 - - log "Configuring toolbox: $toolbox" - tb_run "$toolbox" " - sudo dnf -y upgrade - sudo dnf -y install ${packages[*]} - " -} - -configure_latex_toolbox_extras() { - log "Installing LTEX LS in latex toolbox..." - tb_run latex ' - mkdir -p "$HOME/.local/share/ltex-ls" - cd "$HOME/.local/share/ltex-ls" - LTX_URL="$(curl -sL https://api.github.com/repos/valentjn/ltex-ls/releases/latest | grep -Eo "https.*linux-x64\.tar\.gz" | head -n1)" - [ -n "$LTX_URL" ] || exit 1 - wget -q "$LTX_URL" -O ltex-ls.tar.gz - rm -rf ltex-ls && mkdir -p ltex-ls - tar xzf ltex-ls.tar.gz -C ltex-ls --strip-components=1 - echo "LTEX LS installed at: $HOME/.local/share/ltex-ls/bin/ltex-ls" - ' -} - -configure_mobile_toolbox_extras() { - log "Installing extra mobile tools in mobile toolbox..." - tb_run mobile ' - mkdir -p "$HOME/bin" "$HOME/opt" - - curl -fsSL -o "$HOME/bin/ktlint" \ - https://github.com/pinterest/ktlint/releases/latest/download/ktlint - chmod +x "$HOME/bin/ktlint" - - cd "$HOME/opt" - curl -fsSL -o portable_swiftlint_linux.zip \ - https://github.com/realm/SwiftLint/releases/latest/download/portable_swiftlint_linux.zip - rm -rf swiftlint && mkdir swiftlint - unzip -o portable_swiftlint_linux.zip -d swiftlint >/dev/null - ln -sf "$HOME/opt/swiftlint/swiftlint" "$HOME/bin/swiftlint" - ' -} - -configure_cli_dev_toolbox_extras() { - log "Installing extra version managers in cli-dev toolbox..." - tb_run cli-dev ' - if [ ! -d "$HOME/.jabba" ]; then - curl -fsSL https://github.com/shyiko/jabba/raw/master/install.sh | bash - fi - - if [ ! -d "$HOME/.pyenv" ]; then - curl -fsSL https://pyenv.run | bash - fi - - if [ ! -d "$HOME/.nvm" ]; then - curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash - fi - ' -} - -print_reboot_notice() { - log "" - log "Fedora Atomic setup complete." - log "" - log "Host layered packages were requested via rpm-ostree." - log "Please reboot to activate them:" - log " systemctl reboot" -} - -main() { - require_atomic_fedora - - log "Updating Atomic Fedora..." - sudo rpm-ostree upgrade - - layer_host_packages - setup_default_shell - install_zsh_plugins - setup_tealdeer_and_vim - setup_flatpak - - log "Creating toolboxes..." - create_toolboxes - - install_toolbox_packages cpp-dev - install_toolbox_packages latex - install_toolbox_packages mobile - install_toolbox_packages cli-dev - - configure_latex_toolbox_extras - configure_mobile_toolbox_extras - configure_cli_dev_toolbox_extras - - print_reboot_notice -} - -main "$@" \ No newline at end of file diff --git a/setup.fedora.sh b/setup.fedora.sh deleted file mode 100644 index b0cdb4c..0000000 --- a/setup.fedora.sh +++ /dev/null @@ -1,183 +0,0 @@ -#!/usr/bin/env bash - -# ========================================================= -# Package management -# -# Edit packages in: -# packages/fedora/dnf.txt → dnf packages -# packages/fedora/flatpak.txt → flatpak apps -# packages/fedora/copr.txt → copr repos -# -# Export current system: -# -# # DNF (user-installed packages) -# dnf repoquery --userinstalled --qf "%{name}\n" | sort > packages/fedora/dnf.txt -# -# # Flatpak -# flatpak list --app --columns=application | sort > packages/fedora/flatpak.txt -# -# # COPR repos -# dnf repolist --enabled | grep copr: | awk '{print $1}' | sed 's|copr:copr.fedorainfracloud.org:||' | sort > packages/fedora/copr.txt -# -# ========================================================= - -set -euo pipefail - -REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PKG_DIR="$REPO_DIR/packages/fedora" - -log() { - printf '%s\n' "$*" -} - -require_fedora() { - if [[ ! -f /etc/fedora-release ]]; then - log "error: this script is for Fedora" - exit 1 - fi - - if command -v rpm-ostree >/dev/null 2>&1; then - log "error: rpm-ostree detected; use your Atomic-specific setup instead" - exit 1 - fi - - if [[ $EUID -eq 0 ]]; then - log "error: run as regular user, not root" - exit 1 - fi -} - -dnf_install_from_file() { - local file="$1" - [[ -f "$file" ]] || return 0 - - mapfile -t packages < <(grep -vE '^\s*$|^\s*#' "$file") - [[ ${#packages[@]} -gt 0 ]] || return 0 - - sudo dnf install -y "${packages[@]}" -} - -enable_copr_from_file() { - local file="$1" - [[ -f "$file" ]] || return 0 - - while IFS= read -r repo; do - [[ -z "$repo" || "$repo" =~ ^[[:space:]]*# ]] && continue - sudo dnf copr enable -y "$repo" - done < "$file" -} - -install_flatpaks_from_file() { - local file="$1" - [[ -f "$file" ]] || return 0 - - sudo dnf install -y flatpak - - if ! flatpak remote-list | grep -qi flathub; then - sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo - fi - - while IFS= read -r pkg; do - [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue - flatpak install -y flathub "$pkg" || log "warn: flatpak failed/skipped: $pkg" - done < "$file" -} - -setup_shell() { - mkdir -p "$HOME/.config/tealdeer" - tldr --update || true - mkdir -p "$HOME/.vim/undo" - - if [[ "$(basename "${SHELL}")" != "zsh" ]]; then - log "Changing default shell to zsh..." - chsh -s "$(command -v zsh)" - fi -} - -install_zsh_plugins() { - mkdir -p "$HOME/.zsh" - - [[ -d "$HOME/.zsh/zsh-autosuggestions" ]] || \ - git clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" - - [[ -d "$HOME/.zsh/zsh-syntax-highlighting" ]] || \ - git clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" - - [[ -d "$HOME/.zsh/zsh-autocomplete" ]] || \ - git clone --depth 1 https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" -} - -install_toolbox() { - local version="3.0.1.59888" - local base_dir="$HOME/.config/jetbrains" - local archive="$base_dir/jetbrains-toolbox-$version.tar.gz" - local unpacked="$base_dir/jetbrains-toolbox-$version" - local bin="$unpacked/bin/jetbrains-toolbox" - - mkdir -p "$base_dir" - - if [[ ! -x "$bin" ]]; then - wget -O "$archive" "https://download.jetbrains.com/toolbox/jetbrains-toolbox-$version.tar.gz" - tar -xzf "$archive" -C "$base_dir" - fi - - nohup "$bin" >/dev/null 2>&1 & -} - -install_proton_bridge() { - local tmpdir - tmpdir="$(mktemp -d)" - trap 'rm -rf "$tmpdir"' RETURN - - pushd "$tmpdir" >/dev/null - wget https://proton.me/download/bridge/protonmail-bridge-3.13.0-1.x86_64.rpm - sudo dnf install -y ./protonmail-bridge-3.13.0-1.x86_64.rpm - popd >/dev/null -} - -install_bun() { - curl -fsSL https://bun.com/install | bash -} - -install_junie() { - curl -fsSL https://junie.jetbrains.com/install.sh | bash -} - -setup_services() { - sudo systemctl enable --now tailscaled - sudo tailscale set --operator="$USER" || true -} - -main() { - require_fedora - - log "Updating system..." - sudo dnf -y upgrade --refresh - - log "Configuring extra repos..." - [[ -x "$PKG_DIR/repos.sh" ]] && "$PKG_DIR/repos.sh" - - log "Installing base packages..." - dnf_install_from_file "$PKG_DIR/dnf.txt" - - log "Enabling COPRs..." - enable_copr_from_file "$PKG_DIR/copr.txt" - - log "Installing COPR packages..." - sudo dnf install -y lazygit scrcpy codium steam proton-vpn-gnome-desktop - - log "Installing Flatpaks..." - install_flatpaks_from_file "$PKG_DIR/flatpak.txt" - - setup_shell - install_zsh_plugins - install_toolbox - install_proton_bridge - install_bun - install_junie - setup_services - - log "Fedora setup complete." -} - -main "$@" diff --git a/setup.git-filters.sh b/setup.git-filters.sh deleted file mode 100755 index 203f9b5..0000000 --- a/setup.git-filters.sh +++ /dev/null @@ -1,24 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -# Configures git clean/smudge filters for this dotfiles repo. -# Run once after cloning: ./setup.git-filters.sh - -REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" - -# PKCS#11 provider path filter for SSH config. -# clean: tokenizes real provider paths → @YKCS11@/@OPENSC@ (portable commits) -# smudge: resolves tokens → current platform's real paths (live working tree) -git config filter.pkcs11-provider.clean "$REPO_DIR/ssh/pkcs11-filter.sh clean" -git config filter.pkcs11-provider.smudge "$REPO_DIR/ssh/pkcs11-filter.sh smudge" -git config filter.pkcs11-provider.required true - -# API key scrub filter for junie model configs. -git config filter.scrub-apikey.clean \ - "sed -E 's/(\"apiKey\"[[:space:]]*:[[:space:]]*)\"[^\"]*\"/\\1\"REDACTED\"/'" -git config filter.scrub-apikey.smudge cat -git config filter.scrub-apikey.required true - -echo "Git filters configured:" -echo " pkcs11-provider (clean+smudge) → ssh/config.d/*" -echo " scrub-apikey (clean) → junie/models/*.json" diff --git a/setup.macos.sh b/setup.macos.sh deleted file mode 100644 index 1a2820e..0000000 --- a/setup.macos.sh +++ /dev/null @@ -1,115 +0,0 @@ -#!/usr/bin/env bash - -# ========================================================= -# Package management (Brewfile) -# -# Brewfile location: -# packages/macos/Brewfile -# -# Export current system: -# -# brew bundle dump --describe \ -# --file=packages/macos/Brewfile \ -# --force -# -# Check differences: -# brew bundle check --file=packages/macos/Brewfile -# -# ========================================================= - -set -euo pipefail - -REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -BREWFILE="$REPO_DIR/packages/macos/Brewfile" - -log() { - printf '%s\n' "$*" -} - -ensure_macos() { - if [[ "$(uname -s)" != "Darwin" ]]; then - log "error: setup.macos.sh must be run on macOS" - exit 1 - fi -} - -ensure_homebrew() { - if command -v brew >/dev/null 2>&1; then - log "Homebrew already installed." - return 0 - fi - - log "Installing Homebrew..." - NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" - - if [[ -x /opt/homebrew/bin/brew ]]; then - eval "$(/opt/homebrew/bin/brew shellenv)" - elif [[ -x /usr/local/bin/brew ]]; then - eval "$(/usr/local/bin/brew shellenv)" - fi - - if ! command -v brew >/dev/null 2>&1; then - log "error: Homebrew installation finished but brew is still not on PATH" - exit 1 - fi -} - -ensure_ssh_agent() { - if ! pgrep -u "$USER" ssh-agent >/dev/null 2>&1; then - log "Starting ssh-agent..." - eval "$(ssh-agent -s)" >/dev/null - else - log "ssh-agent already running." - fi -} - -add_ssh_keys_to_keychain() { - local ssh_dir="$HOME/.ssh" - - [[ -d "$ssh_dir" ]] || return 0 - - while IFS= read -r -d '' key; do - case "$(basename "$key")" in - *.pub|known_hosts|config) - continue - ;; - esac - - log "Adding SSH key to Apple keychain: $key" - ssh-add --apple-use-keychain "$key" >/dev/null 2>&1 || true - done < <(find "$ssh_dir" -type f -perm 600 -print0 2>/dev/null) -} - -install_brew_packages() { - if [[ -f "$BREWFILE" ]]; then - log "Installing Homebrew packages from Brewfile..." - brew bundle --file="$BREWFILE" - else - log "warn: no Brewfile found at $BREWFILE" - fi -} - -install_vim_theme() { - local theme_dir="$HOME/.vim/pack/themes/start/dracula" - mkdir -p "$(dirname "$theme_dir")" - - if [[ ! -d "$theme_dir" ]]; then - log "Installing Dracula vim theme..." - git clone https://github.com/dracula/vim.git "$theme_dir" - else - log "Dracula vim theme already installed." - fi -} - -main() { - ensure_macos - log "Starting macOS setup..." - ensure_homebrew - ensure_ssh_agent - add_ssh_keys_to_keychain - install_brew_packages - install_vim_theme - log "macOS setup complete." -} - -main "$@" \ No newline at end of file diff --git a/setup.manjaro.sh b/setup.manjaro.sh deleted file mode 100644 index c8f599b..0000000 --- a/setup.manjaro.sh +++ /dev/null @@ -1,177 +0,0 @@ -#!/usr/bin/env bash -set -euo pipefail - -# Package manifests: -# packages/manjaro/pacman.txt -# packages/manjaro/aur.txt -# packages/manjaro/external.txt -# -# Export explicitly installed pacman packages: -# pacman -Qqe | sort > packages/manjaro/pacman.txt -# -# Export foreign/AUR packages: -# pacman -Qqm | sort > packages/manjaro/aur.txt - -REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" -PKG_DIR="$REPO_DIR/packages/manjaro" - -log() { - printf '%s\n' "$*" -} - -require_manjaro() { - if [[ ! -f /etc/manjaro-release ]]; then - log "error: this script is for Manjaro" - exit 1 - fi - - if [[ $EUID -eq 0 ]]; then - log "error: run as a regular user, not root" - exit 1 - fi -} - -read_manifest() { - local file="$1" - [[ -f "$file" ]] || return 0 - grep -vE '^\s*$|^\s*#' "$file" -} - -install_pacman_packages() { - local file="$PKG_DIR/pacman.txt" - mapfile -t packages < <(read_manifest "$file") - - [[ ${#packages[@]} -gt 0 ]] || { - log "No pacman packages to install." - return 0 - } - - log "Updating system..." - sudo pacman -Syu --noconfirm - - log "Installing pacman packages..." - sudo pacman -S --needed --noconfirm "${packages[@]}" -} - -ensure_yay() { - if command -v yay >/dev/null 2>&1; then - return 0 - fi - - log "Installing yay..." - sudo pacman -S --needed --noconfirm base-devel git - - local tmpdir - tmpdir="$(mktemp -d)" - trap 'rm -rf "$tmpdir"' RETURN - - git clone https://aur.archlinux.org/yay.git "$tmpdir/yay" - pushd "$tmpdir/yay" >/dev/null - makepkg -si --noconfirm - popd >/dev/null -} - -install_aur_packages() { - local file="$PKG_DIR/aur.txt" - mapfile -t packages < <(read_manifest "$file") - - [[ ${#packages[@]} -gt 0 ]] || { - log "No AUR packages to install." - return 0 - } - - ensure_yay - - log "Installing AUR packages..." - yay -S --needed --noconfirm "${packages[@]}" -} - -setup_zsh_plugins() { - log "Installing zsh plugins..." - mkdir -p "$HOME/.zsh" - - [[ -d "$HOME/.zsh/zsh-autosuggestions" ]] || \ - git clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" - - [[ -d "$HOME/.zsh/zsh-syntax-highlighting" ]] || \ - git clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" - - [[ -d "$HOME/.zsh/zsh-autocomplete" ]] || \ - git clone --depth 1 https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" -} - -setup_default_shell() { - if command -v zsh >/dev/null 2>&1 && [[ "$(basename "${SHELL}")" != "zsh" ]]; then - log "Changing default shell to zsh..." - chsh -s "$(command -v zsh)" - log "Shell changed. Log out/in for it to take effect." - fi -} - -setup_printer() { - if systemctl list-unit-files | grep -q '^cups\.service'; then - log "Enabling cups..." - sudo systemctl enable --now cups.service || true - fi -} - -setup_firewall() { - if pacman -Q nftables >/dev/null 2>&1; then - sudo systemctl enable --now nftables || true - fi - - if command -v ufw >/dev/null 2>&1; then - sudo ufw --force enable || true - fi -} - -setup_clamav() { - if systemctl list-unit-files | grep -q '^clamav-freshclam\.service'; then - sudo systemctl enable --now clamav-freshclam.service || true - fi -} - -run_external_scripts() { - local dir="$PKG_DIR/external" - - [[ -d "$dir" ]] || { - log "No external directory found." - return 0 - } - - shopt -s nullglob - local scripts=("$dir"/*.sh) - shopt -u nullglob - - [[ ${#scripts[@]} -gt 0 ]] || { - log "No external scripts to run." - return 0 - } - - log "Running external setup scripts..." - local script - for script in "${scripts[@]}"; do - if [[ -x "$script" ]]; then - log "-> $(basename "$script")" - "$script" - else - log "skip: not executable: $script" - fi - done -} - -main() { - require_manjaro - install_pacman_packages - install_aur_packages - setup_zsh_plugins - setup_default_shell - setup_printer - setup_firewall - setup_clamav - run_external_scripts - log "" - log "Manjaro setup complete." -} - -main "$@" \ No newline at end of file diff --git a/setup.sh b/setup.sh index 1e421fd..22f0f52 100755 --- a/setup.sh +++ b/setup.sh @@ -1,114 +1,300 @@ #!/usr/bin/env bash set -euo pipefail +# Root setup runner — orchestration only. +# Detects the OS, discovers numbered step scripts under setup/general/ and the +# detected setup// directory, applies selection filters, and runs each +# selected step as a separate process via `presteps` then `run`. +# No setup logic lives in this file. + REPO_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +SETUP_DIR="$REPO_DIR/setup" -log() { - printf '%s\n' "$*" -} +log() { printf '%s\n' "$*"; } +err() { printf 'error: %s\n' "$*" >&2; } -link_path() { - local src="$1" - local dest="$2" +usage() { + cat <<'EOF' +Usage: setup.sh [MODE] [SELECTORS] - if [[ ! -e "$src" ]]; then - log "skip: source does not exist: $src" - return 0 - fi +OS setup runner. Discovers numbered step scripts under setup/general/ and the +detected OS directory (setup//), then runs each selected step's +presteps + run as a separate process. - mkdir -p "$(dirname "$dest")" +OS detection: + Darwin -> macos + Linux + /etc/fedora-release + + rpm-ostree -> fedora-atomic + Linux + /etc/fedora-release -> fedora + Linux + /etc/manjaro-release -> manjaro - if [[ -L "$dest" ]]; then - ln -sfn "$src" "$dest" - log "linked: $dest -> $src" - return 0 - fi +Modes: + (default) | --all run all discovered steps (general first, then OS) + --only SEL[,SEL,...] run exactly the selected discovered steps + --exclude SEL[,SEL,...] run all discovered steps except the selected ones + --interactive choose steps with fzf --multi (falls back to flags) + --list list discovered steps with help text and exit + --help show this help and exit - if [[ -e "$dest" ]]; then - local backup="${dest}.bak.$(date +%Y%m%d%H%M%S)" - mv "$dest" "$backup" - log "backup: $dest -> $backup" - fi +Selectors (matched in order: /, , ): + general/01-symlinks.sh + 01-symlinks.sh + 01-symlinks - ln -sfn "$src" "$dest" - log "linked: $dest -> $src" +Examples: + ./setup.sh + ./setup.sh --all + ./setup.sh --only general/01-symlinks.sh + ./setup.sh --only fedora/06-flatpak-apps.sh,fedora/08-zsh-plugins.sh + ./setup.sh --exclude fedora/14-tailscale.sh + ./setup.sh --interactive + ./setup.sh --list +EOF } -setup_symlinks() { - log "Setting up symlinks..." +detect_os() { + case "$(uname -s)" in + Darwin) printf 'macos' ;; + Linux) + if [[ -f /etc/fedora-release ]]; then + if command -v rpm-ostree >/dev/null 2>&1; then + printf 'fedora-atomic' + else + printf 'fedora' + fi + elif [[ -f /etc/manjaro-release ]]; then + printf 'manjaro' + else + return 1 + fi + ;; + *) return 1 ;; + esac +} - mkdir -p "$HOME/.config" - mkdir -p "$HOME/.ssh" +# Print executable *.sh step paths (absolute) in a scope dir, sorted lexically. +discover_scope() { + local dir="$1" + [[ -d "$dir" ]] || return 0 + local f + while IFS= read -r f; do + [[ -x "$f" ]] && printf '%s\n' "$f" + done < <(find "$dir" -maxdepth 1 -type f -name '*.sh' 2>/dev/null | sort) +} - link_path "$REPO_DIR/zshrc" "$HOME/.zshrc" - link_path "$REPO_DIR/vimrc" "$HOME/.vimrc" - link_path "$REPO_DIR/gitconfig" "$HOME/.gitconfig" +# Step registry: parallel arrays of scope and absolute path. +declare -a STEP_SCOPE=() +declare -a STEP_PATH=() - link_path "$REPO_DIR/vim" "$HOME/.vim" - link_path "$REPO_DIR/nvim" "$HOME/.config/nvim" - link_path "$REPO_DIR/lazygit" "$HOME/.config/lazygit" +add_steps_from() { + local scope="$1" dir="$2" path + while IFS= read -r path; do + [[ -n "$path" ]] || continue + STEP_SCOPE+=("$scope") + STEP_PATH+=("$path") + done < <(discover_scope "$dir") +} + +step_count() { printf '%s\n' "${#STEP_PATH[@]}"; } + +# Fully-qualified ID for step index $1: / +step_fq() { + local idx="$1" + printf '%s/%s\n' "${STEP_SCOPE[$idx]}" "$(basename "${STEP_PATH[$idx]}")" +} - link_path "$REPO_DIR/junie" "$HOME/.junie" +# Return 0 if selector $1 matches step index $2. +step_matches() { + local selector="$1" idx="$2" + local scope path fname base fq + scope="${STEP_SCOPE[$idx]}" + path="${STEP_PATH[$idx]}" + fname="$(basename "$path")" + base="${fname%.sh}" + fq="$scope/$fname" + [[ "$selector" == "$fq" || "$selector" == "$fname" || "$selector" == "$base" ]] +} - [[ -d "$REPO_DIR/ghostty" ]] && link_path "$REPO_DIR/ghostty" "$HOME/.config/ghostty" - [[ -d "$REPO_DIR/Nextcloud" ]] && link_path "$REPO_DIR/Nextcloud" "$HOME/.config/Nextcloud" +# Count how many discovered steps a selector matches. +selector_match_count() { + local selector="$1" idx count=0 + for idx in "${!STEP_PATH[@]}"; do + if step_matches "$selector" "$idx"; then count=$((count + 1)); fi + done + printf '%s\n' "$count" +} - [[ -f "$REPO_DIR/ssh/config" ]] && link_path "$REPO_DIR/ssh/config" "$HOME/.ssh/config" - [[ -f "$REPO_DIR/ssh/known_hosts" ]] && link_path "$REPO_DIR/ssh/known_hosts" "$HOME/.ssh/known_hosts" +# Validate that every selector in a comma list matches exactly one step. +validate_selectors() { + local list="$1" IFS=',' + local sel + for sel in $list; do + sel="${sel# }"; sel="${sel% }" + [[ -n "$sel" ]] || continue + local n + n="$(selector_match_count "$sel")" + if [[ "$n" -eq 0 ]]; then + err "unknown step selector: $sel" + exit 1 + fi + if [[ "$n" -gt 1 ]]; then + err "ambiguous step selector: $sel (matches $n steps)" + exit 1 + fi + done +} - chmod 700 "$HOME/.ssh" || true +# Print "scope/filenamehelp" for each discovered step. +list_steps() { + local idx + for idx in "${!STEP_PATH[@]}"; do + local fq="${STEP_SCOPE[$idx]}/$(basename "${STEP_PATH[$idx]}")" + local help_text + help_text="$("${STEP_PATH[$idx]}" help 2>/dev/null | head -1 || true)" + printf '%s\t%s\n' "$fq" "$help_text" + done +} - # Configure git clean/smudge filters (run once per clone) - if [[ -x "$REPO_DIR/setup.git-filters.sh" ]]; then - "$REPO_DIR/setup.git-filters.sh" +# Interactive selection via fzf --multi. Prints selected fully-qualified IDs. +interactive_select() { + if ! command -v fzf >/dev/null 2>&1; then + err "interactive mode requires fzf, which was not found." + err "Use flag-based selection instead, e.g.: ./setup.sh --only general/01-symlinks.sh" + exit 1 fi + local entries=() idx + for idx in "${!STEP_PATH[@]}"; do + local fq="${STEP_SCOPE[$idx]}/$(basename "${STEP_PATH[$idx]}")" + local help_text + help_text="$("${STEP_PATH[$idx]}" help 2>/dev/null | head -1 || true)" + entries+=("$fq — $help_text") + done + printf '%s\n' "${entries[@]}" | fzf --multi --prompt="setup steps> " \ + | sed 's/ — .*//' } -run_platform_setup() { - case "$(uname -s)" in - Darwin) - [[ -x "$REPO_DIR/setup.macos.sh" ]] || { - log "warn: setup.macos.sh not found or not executable" - return 0 - } - "$REPO_DIR/setup.macos.sh" +run_step() { + local scope="$1" path="$2" + local label="$scope/$(basename "$path")" + log "==> $label: presteps" + if ! "$path" presteps; then + log " presteps failed; skipping run" + return 2 + fi + log "==> $label: run" + if ! "$path" run; then + log " run failed" + return 1 + fi + return 0 +} + +main() { + local mode="all" + local selectors="" + + while [[ $# -gt 0 ]]; do + case "$1" in + --help|-h) usage; exit 0 ;; + --list) mode="list"; shift ;; + --all) mode="all"; shift ;; + --only) mode="only"; selectors="${2:-}"; shift 2 ;; + --exclude) mode="exclude"; selectors="${2:-}"; shift 2 ;; + --interactive) mode="interactive"; shift ;; + --only=*) mode="only"; selectors="${1#--only=}"; shift ;; + --exclude=*) mode="exclude"; selectors="${1#--exclude=}"; shift ;; + *) err "unknown argument: $1"; usage >&2; exit 2 ;; + esac + done + + local os_id + if ! os_id="$(detect_os)"; then + err "unsupported or undetectable OS" + exit 1 + fi + log "Detected OS: $os_id" + + add_steps_from "general" "$SETUP_DIR/general" + add_steps_from "$os_id" "$SETUP_DIR/$os_id" + + if [[ "$(step_count)" -eq 0 ]]; then + err "no setup steps discovered under setup/general/ or setup/$os_id/" + exit 1 + fi + + if [[ "$mode" == "list" ]]; then + list_steps | column -t -s $'\t' 2>/dev/null || list_steps + exit 0 + fi + + # Build the selected index list. + local selected=() idx + case "$mode" in + all) + for idx in "${!STEP_PATH[@]}"; do selected+=("$idx"); done ;; - Linux) - if [[ -f /etc/fedora-release ]]; then - if command -v rpm-ostree >/dev/null 2>&1; then - [[ -x "$REPO_DIR/setup.atomic-fedora.sh" ]] || { - log "warn: setup.atomic-fedora.sh not found or not executable" - return 0 - } - "$REPO_DIR/setup.atomic-fedora.sh" - else - [[ -x "$REPO_DIR/setup.fedora.sh" ]] || { - log "warn: setup.fedora.sh not found or not executable" - return 0 - } - "$REPO_DIR/setup.fedora.sh" - fi - elif [[ -f /etc/manjaro-release ]]; then - [[ -x "$REPO_DIR/setup.manjaro.sh" ]] || { - log "warn: setup.manjaro.sh not found or not executable" - return 0 - } - "$REPO_DIR/setup.manjaro.sh" - else - log "warn: unsupported Linux distribution" - fi + only) + validate_selectors "$selectors" + local IFS=',' + local sel + for sel in $selectors; do + sel="${sel# }"; sel="${sel% }" + [[ -n "$sel" ]] || continue + for idx in "${!STEP_PATH[@]}"; do + if step_matches "$sel" "$idx"; then selected+=("$idx"); fi + done + done + ;; + exclude) + validate_selectors "$selectors" + local IFS=',' + local sel + for idx in "${!STEP_PATH[@]}"; do + local drop=0 + for sel in $selectors; do + sel="${sel# }"; sel="${sel% }" + [[ -n "$sel" ]] || continue + if step_matches "$sel" "$idx"; then drop=1; break; fi + done + [[ "$drop" -eq 0 ]] && selected+=("$idx") + done ;; - *) - log "warn: unsupported OS: $(uname -s)" + interactive) + local picks pick + picks="$(interactive_select)" || { err "no steps selected"; exit 1; } + while IFS= read -r pick; do + pick="${pick# }"; pick="${pick% }" + [[ -n "$pick" ]] || continue + for idx in "${!STEP_PATH[@]}"; do + if step_matches "$pick" "$idx"; then selected+=("$idx"); fi + done + done <<< "$picks" ;; esac -} -main() { - log "Starting base setup..." - setup_symlinks - run_platform_setup - log "Base setup complete." + if [[ "${#selected[@]}" -eq 0 ]]; then + err "no steps selected" + exit 1 + fi + + log "Running ${#selected[@]} step(s) for $os_id." + local executed=0 failed=0 skipped=0 + for idx in "${selected[@]}"; do + if run_step "${STEP_SCOPE[$idx]}" "${STEP_PATH[$idx]}"; then + executed=$((executed + 1)) + else + local rc=$? + if [[ "$rc" -eq 2 ]]; then + skipped=$((skipped + 1)) + else + failed=$((failed + 1)) + fi + fi + done + + log "" + log "Summary: executed=$executed failed=$failed skipped=$skipped" + [[ "$failed" -eq 0 ]] || exit 1 } main "$@" \ No newline at end of file diff --git a/setup/fedora-atomic/01-system-upgrade.sh b/setup/fedora-atomic/01-system-upgrade.sh new file mode 100755 index 0000000..64ec79c --- /dev/null +++ b/setup/fedora-atomic/01-system-upgrade.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists rpm-ostree || die "rpm-ostree not found; this does not look like Fedora Atomic" +} + +help() { + cat <<'EOF' +Upgrade the system via `sudo rpm-ostree upgrade`. +Idempotent: safe to run repeatedly. +EOF +} + +run() { + log "Upgrading system via rpm-ostree..." + sudo rpm-ostree upgrade +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/02-host-packages.sh b/setup/fedora-atomic/02-host-packages.sh new file mode 100755 index 0000000..20c0ca0 --- /dev/null +++ b/setup/fedora-atomic/02-host-packages.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +RPM_OSTREE_FILE="$SCRIPT_DIR/rpm-ostree.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists rpm-ostree || die "rpm-ostree not found" +} + +help() { + cat <<'EOF' +Layer host packages from setup/fedora-atomic/rpm-ostree.txt via rpm-ostree. +Idempotent: rpm-ostree install is a no-op for already-layered packages. +EOF +} + +run() { + layer_host_packages "$RPM_OSTREE_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/03-default-shell.sh b/setup/fedora-atomic/03-default-shell.sh new file mode 100755 index 0000000..fd2cdab --- /dev/null +++ b/setup/fedora-atomic/03-default-shell.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists zsh || die "zsh not found; layer it via rpm-ostree first" +} + +help() { + cat <<'EOF' +Change the default shell to zsh if not already set. +Idempotent: skips when zsh is already the default shell. +EOF +} + +run() { + ensure_default_shell_zsh +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/04-zsh-plugins.sh b/setup/fedora-atomic/04-zsh-plugins.sh new file mode 100755 index 0000000..8613413 --- /dev/null +++ b/setup/fedora-atomic/04-zsh-plugins.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + require_command git +} + +help() { + cat <<'EOF' +Clone ZSH plugins (zsh-autosuggestions, zsh-syntax-highlighting, +zsh-autocomplete) into ~/.zsh/. Idempotent: skips existing directories. +EOF +} + +run() { + log "Installing ZSH plugins..." + install_zsh_plugins +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/05-tealdeer.sh b/setup/fedora-atomic/05-tealdeer.sh new file mode 100755 index 0000000..ce81d5e --- /dev/null +++ b/setup/fedora-atomic/05-tealdeer.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + require_command mkdir +} + +help() { + cat <<'EOF' +Create tealdeer config directory and update tldr cache. +Idempotent: directory creation is a no-op when it exists. +EOF +} + +run() { + setup_tealdeer +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/06-flatpak-remote.sh b/setup/fedora-atomic/06-flatpak-remote.sh new file mode 100755 index 0000000..c9ba431 --- /dev/null +++ b/setup/fedora-atomic/06-flatpak-remote.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" +} + +help() { + cat <<'EOF' +Ensure Flatpak is installed and the Flathub remote exists. +Idempotent: skips when Flatpak and Flathub are already present. +EOF +} + +run() { + log "Setting up Flatpak remote..." + ensure_flatpak_remote +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/07-flatpak-apps.sh b/setup/fedora-atomic/07-flatpak-apps.sh new file mode 100755 index 0000000..dadcdb3 --- /dev/null +++ b/setup/fedora-atomic/07-flatpak-apps.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +FLATPAK_FILE="$SCRIPT_DIR/flatpak.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists flatpak || die "flatpak not found; run 06-flatpak-remote first" +} + +help() { + cat <<'EOF' +Install Flatpak apps listed in setup/fedora-atomic/flatpak.txt. +Idempotent: skips apps that are already installed. +EOF +} + +run() { + log "Installing Flatpak apps..." + flatpak_install_from_manifest "$FLATPAK_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/08-toolbox-create.sh b/setup/fedora-atomic/08-toolbox-create.sh new file mode 100755 index 0000000..1b9e649 --- /dev/null +++ b/setup/fedora-atomic/08-toolbox-create.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +TOOLBOXES_FILE="$SCRIPT_DIR/toolboxes.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists toolbox || die "toolbox not found" +} + +help() { + cat <<'EOF' +Create toolboxes listed in setup/fedora-atomic/toolboxes.txt. +Idempotent: skips toolboxes that already exist. +EOF +} + +run() { + log "Creating toolboxes..." + create_toolboxes "$TOOLBOXES_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/09-toolbox-packages.sh b/setup/fedora-atomic/09-toolbox-packages.sh new file mode 100755 index 0000000..9fe456e --- /dev/null +++ b/setup/fedora-atomic/09-toolbox-packages.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists toolbox || die "toolbox not found" +} + +help() { + cat <<'EOF' +Install packages inside each toolbox from setup/fedora-atomic/toolboxes/*.txt. +Idempotent: dnf install inside toolboxes skips already-installed packages. +EOF +} + +run() { + log "Installing toolbox packages..." + install_toolbox_packages cpp-dev + install_toolbox_packages latex + install_toolbox_packages mobile + install_toolbox_packages cli-dev +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/10-toolbox-latex.sh b/setup/fedora-atomic/10-toolbox-latex.sh new file mode 100755 index 0000000..b6682b6 --- /dev/null +++ b/setup/fedora-atomic/10-toolbox-latex.sh @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +LTEX_DIR='$HOME/.local/share/ltex-ls/bin/ltex-ls' + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists toolbox || die "toolbox not found" +} + +help() { + cat <<'EOF' +Install LTEX LS (LanguageTool for LaTeX) inside the latex toolbox. +Idempotent: skips when the ltex-ls binary already exists in the toolbox. +EOF +} + +run() { + log "Checking LTEX LS in latex toolbox..." + if tb_run latex "[ -x $LTEX_DIR ]" 2>/dev/null; then + log "LTEX LS already installed in latex toolbox." + return 0 + fi + + log "Installing LTEX LS in latex toolbox..." + tb_run latex ' + mkdir -p "$HOME/.local/share/ltex-ls" + cd "$HOME/.local/share/ltex-ls" + LTX_URL="$(curl -sL https://api.github.com/repos/valentjn/ltex-ls/releases/latest | grep -Eo "https.*linux-x64\.tar\.gz" | head -n1)" + [ -n "$LTX_URL" ] || exit 1 + wget -q "$LTX_URL" -O ltex-ls.tar.gz + rm -rf ltex-ls && mkdir -p ltex-ls + tar xzf ltex-ls.tar.gz -C ltex-ls --strip-components=1 + echo "LTEX LS installed at: $HOME/.local/share/ltex-ls/bin/ltex-ls" + ' +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/11-toolbox-mobile.sh b/setup/fedora-atomic/11-toolbox-mobile.sh new file mode 100755 index 0000000..6211d46 --- /dev/null +++ b/setup/fedora-atomic/11-toolbox-mobile.sh @@ -0,0 +1,55 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists toolbox || die "toolbox not found" +} + +help() { + cat <<'EOF' +Install ktlint and SwiftLint inside the mobile toolbox. +Idempotent: skips when the tools already exist in the toolbox. +EOF +} + +run() { + log "Installing mobile tools in mobile toolbox..." + + tb_run mobile ' + mkdir -p "$HOME/bin" "$HOME/opt" + + if [ ! -x "$HOME/bin/ktlint" ]; then + curl -fsSL -o "$HOME/bin/ktlint" \ + https://github.com/pinterest/ktlint/releases/latest/download/ktlint + chmod +x "$HOME/bin/ktlint" + fi + + if [ ! -x "$HOME/bin/swiftlint" ]; then + cd "$HOME/opt" + curl -fsSL -o portable_swiftlint_linux.zip \ + https://github.com/realm/SwiftLint/releases/latest/download/portable_swiftlint_linux.zip + rm -rf swiftlint && mkdir swiftlint + unzip -o portable_swiftlint_linux.zip -d swiftlint >/dev/null + ln -sf "$HOME/opt/swiftlint/swiftlint" "$HOME/bin/swiftlint" + fi + ' +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/12-toolbox-cli-dev.sh b/setup/fedora-atomic/12-toolbox-cli-dev.sh new file mode 100755 index 0000000..e8960a4 --- /dev/null +++ b/setup/fedora-atomic/12-toolbox-cli-dev.sh @@ -0,0 +1,50 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists toolbox || die "toolbox not found" +} + +help() { + cat <<'EOF' +Install version managers (Jabba, Pyenv, NVM) inside the cli-dev toolbox. +Idempotent: skips when each manager is already installed. +EOF +} + +run() { + log "Installing version managers in cli-dev toolbox..." + + tb_run cli-dev ' + if [ ! -d "$HOME/.jabba" ]; then + curl -fsSL https://github.com/shyiko/jabba/raw/master/install.sh | bash + fi + + if [ ! -d "$HOME/.pyenv" ]; then + curl -fsSL https://pyenv.run | bash + fi + + if [ ! -d "$HOME/.nvm" ]; then + curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/master/install.sh | bash + fi + ' +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/99-reboot-notice.sh b/setup/fedora-atomic/99-reboot-notice.sh new file mode 100755 index 0000000..ed34f84 --- /dev/null +++ b/setup/fedora-atomic/99-reboot-notice.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + return 0 +} + +help() { + cat <<'EOF' +Print a reminder to reboot if rpm-ostree layered packages were requested. +Always runs (informational only). +EOF +} + +run() { + log "" + log "Fedora Atomic setup complete." + log "" + log "If host packages were layered via rpm-ostree, reboot to activate them:" + log " systemctl reboot" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora-atomic/common.bash b/setup/fedora-atomic/common.bash new file mode 100644 index 0000000..9566067 --- /dev/null +++ b/setup/fedora-atomic/common.bash @@ -0,0 +1,139 @@ +#!/usr/bin/env bash +# Fedora Atomic-specific helper library for setup steps. +# +# Sourced by Fedora Atomic step scripts via: +# source "$SCRIPT_DIR/common.bash" +# This file is NOT executable — the runner does not discover it as a step. +# +# Contains rpm-ostree, Flatpak, toolbox, and Atomic-specific installer/downloader +# guards. Platform-neutral primitives live in setup/general/common.bash. + +[[ -n "${_SETUP_FEDORA_ATOMIC_COMMON:-}" ]] && return 0 +_SETUP_FEDORA_ATOMIC_COMMON=1 + +# Source general helpers if not already sourced. +if [[ -z "${_SETUP_GENERAL_COMMON:-}" ]]; then + # shellcheck source=../general/common.bash + source "$REPO_DIR/setup/general/common.bash" +fi + +# Layer host packages from a manifest via rpm-ostree. Idempotent: rpm-ostree +# install is a no-op for already-layered packages. +layer_host_packages() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + local packages=() + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + packages+=("$pkg") + done < "$file" + + [[ ${#packages[@]} -gt 0 ]] || { log "no host packages to layer."; return 0; } + + log "Layering host packages with rpm-ostree..." + sudo rpm-ostree install "${packages[@]}" + log "Host package layering complete. Reboot required to use newly layered packages." +} + +# Ensure Flatpak is installed and Flathub remote exists. Idempotent. +ensure_flatpak_remote() { + command_exists flatpak || sudo rpm-ostree install flatpak 2>/dev/null || sudo dnf install -y flatpak 2>/dev/null || true + + if flatpak remote-list 2>/dev/null | grep -qi flathub; then + log "Flathub remote already exists." + return 0 + fi + log "Adding Flathub remote..." + sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo || true + flatpak update -y 2>/dev/null || true +} + +# Install Flatpak apps from a manifest. Skips already-installed apps. +flatpak_install_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + while IFS= read -r app; do + [[ -z "$app" || "$app" =~ ^[[:space:]]*# ]] && continue + if flatpak list --app 2>/dev/null | grep -qF "$app"; then + log "Flatpak already installed: $app" + continue + fi + log "Installing Flatpak: $app" + flatpak install -y flathub "$app" || log "warn: failed/skipped flatpak $app" + done < "$file" +} + +# Change default shell to zsh if not already set. Idempotent. +ensure_default_shell_zsh() { + if [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then + log "Default shell is already zsh." + return 0 + fi + log "Changing default shell to zsh..." + chsh -s "$(command -v zsh)" || log "warn: chsh failed (may be expected in containers)" + log "Shell changed. Log out/in or reboot for it to take effect." +} + +# Install ZSH plugins via git clone. Idempotent. +install_zsh_plugins() { + ensure_dir "$HOME/.zsh" + + ensure_git_clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" + ensure_git_clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" + ensure_git_clone https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" +} + +# Create tealdeer config dir and update tldr cache. Idempotent. +setup_tealdeer() { + ensure_dir "$HOME/.config/tealdeer" + if command_exists tldr; then + tldr --update 2>/dev/null || true + fi +} + +# Run a command inside a toolbox container. +tb_run() { + local name="$1" + shift + toolbox run --container "$name" bash -lc "$*" +} + +# Create toolboxes from a manifest. Skips already-existing toolboxes. +create_toolboxes() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + while IFS= read -r box; do + [[ -z "$box" || "$box" =~ ^[[:space:]]*# ]] && continue + if toolbox list 2>/dev/null | grep -qF "$box"; then + log "Toolbox already exists: $box" + continue + fi + log "Creating toolbox: $box" + toolbox create --container "$box" || log "warn: toolbox create failed for $box" + done < "$file" +} + +# Install packages inside a toolbox from its manifest. +install_toolbox_packages() { + local toolbox="$1" + local manifest="$SCRIPT_DIR/toolboxes/$toolbox.txt" + + [[ -f "$manifest" ]] || { log "no manifest for toolbox $toolbox"; return 0; } + + local packages=() + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + packages+=("$pkg") + done < "$manifest" + + [[ ${#packages[@]} -gt 0 ]] || { log "no packages for toolbox $toolbox"; return 0; } + + log "Installing packages in toolbox: $toolbox" + tb_run "$toolbox" " + sudo dnf -y upgrade + sudo dnf -y install ${packages[*]} + " +} \ No newline at end of file diff --git a/packages/fedora-atomic/flatpak.txt b/setup/fedora-atomic/flatpak.txt similarity index 100% rename from packages/fedora-atomic/flatpak.txt rename to setup/fedora-atomic/flatpak.txt diff --git a/packages/fedora-atomic/rpm-ostree.txt b/setup/fedora-atomic/rpm-ostree.txt similarity index 97% rename from packages/fedora-atomic/rpm-ostree.txt rename to setup/fedora-atomic/rpm-ostree.txt index acec221..1516fe4 100644 --- a/packages/fedora-atomic/rpm-ostree.txt +++ b/setup/fedora-atomic/rpm-ostree.txt @@ -21,6 +21,7 @@ unzip tar # Host desktop / utilities +kitty wireshark openscad eog diff --git a/packages/fedora-atomic/toolboxes.txt b/setup/fedora-atomic/toolboxes.txt similarity index 100% rename from packages/fedora-atomic/toolboxes.txt rename to setup/fedora-atomic/toolboxes.txt diff --git a/packages/fedora-atomic/toolboxes/cli-dev.txt b/setup/fedora-atomic/toolboxes/cli-dev.txt similarity index 100% rename from packages/fedora-atomic/toolboxes/cli-dev.txt rename to setup/fedora-atomic/toolboxes/cli-dev.txt diff --git a/packages/fedora-atomic/toolboxes/cpp-dev.txt b/setup/fedora-atomic/toolboxes/cpp-dev.txt similarity index 100% rename from packages/fedora-atomic/toolboxes/cpp-dev.txt rename to setup/fedora-atomic/toolboxes/cpp-dev.txt diff --git a/packages/fedora-atomic/toolboxes/latex.txt b/setup/fedora-atomic/toolboxes/latex.txt similarity index 100% rename from packages/fedora-atomic/toolboxes/latex.txt rename to setup/fedora-atomic/toolboxes/latex.txt diff --git a/packages/fedora-atomic/toolboxes/mobile.txt b/setup/fedora-atomic/toolboxes/mobile.txt similarity index 100% rename from packages/fedora-atomic/toolboxes/mobile.txt rename to setup/fedora-atomic/toolboxes/mobile.txt diff --git a/setup/fedora/01-system-update.sh b/setup/fedora/01-system-update.sh new file mode 100755 index 0000000..c985c43 --- /dev/null +++ b/setup/fedora/01-system-update.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists dnf || die "dnf not found" +} + +help() { + cat <<'EOF' +Update system packages via `sudo dnf -y upgrade --refresh`. +Idempotent: dnf upgrade is safe to run repeatedly. +EOF +} + +run() { + log "Updating system..." + sudo dnf -y upgrade --refresh +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/02-copr-repos.sh b/setup/fedora/02-copr-repos.sh new file mode 100755 index 0000000..f96d269 --- /dev/null +++ b/setup/fedora/02-copr-repos.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +COPR_FILE="$SCRIPT_DIR/copr.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists dnf || die "dnf not found" +} + +help() { + cat <<'EOF' +Enable COPR repositories listed in setup/fedora/copr.txt. +Idempotent: skips repos that are already enabled. +EOF +} + +run() { + log "Enabling COPR repositories..." + enable_copr_from_manifest "$COPR_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/03-dnf-packages.sh b/setup/fedora/03-dnf-packages.sh new file mode 100755 index 0000000..d50b47d --- /dev/null +++ b/setup/fedora/03-dnf-packages.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +DNF_FILE="$SCRIPT_DIR/dnf.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists dnf || die "dnf not found" +} + +help() { + cat <<'EOF' +Install dnf packages listed in setup/fedora/dnf.txt. +Idempotent: dnf install skips already-installed packages. +EOF +} + +run() { + log "Installing dnf packages..." + dnf_install_from_manifest "$DNF_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/04-copr-packages.sh b/setup/fedora/04-copr-packages.sh new file mode 100755 index 0000000..774bb79 --- /dev/null +++ b/setup/fedora/04-copr-packages.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists dnf || die "dnf not found" +} + +help() { + cat <<'EOF' +Install COPR-dependent packages (lazygit, scrcpy, codium, steam, +proton-vpn-gnome-desktop). Idempotent: dnf install skips already-installed. +EOF +} + +run() { + log "Installing COPR packages..." + sudo dnf install -y lazygit scrcpy codium steam proton-vpn-gnome-desktop +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/05-flatpak-runtime.sh b/setup/fedora/05-flatpak-runtime.sh new file mode 100755 index 0000000..645f3aa --- /dev/null +++ b/setup/fedora/05-flatpak-runtime.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" +} + +help() { + cat <<'EOF' +Install Flatpak and ensure the Flathub remote exists. +Idempotent: skips when Flatpak and Flathub are already present. +EOF +} + +run() { + log "Setting up Flatpak runtime..." + ensure_flatpak_runtime +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/06-flatpak-apps.sh b/setup/fedora/06-flatpak-apps.sh new file mode 100755 index 0000000..fc1188d --- /dev/null +++ b/setup/fedora/06-flatpak-apps.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +FLATPAK_FILE="$SCRIPT_DIR/flatpak.txt" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists flatpak || die "flatpak not found; run 05-flatpak-runtime first" +} + +help() { + cat <<'EOF' +Install Flatpak apps listed in setup/fedora/flatpak.txt. +Idempotent: skips apps that are already installed. +EOF +} + +run() { + log "Installing Flatpak apps..." + flatpak_install_from_manifest "$FLATPAK_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/07-default-shell.sh b/setup/fedora/07-default-shell.sh new file mode 100755 index 0000000..487ca42 --- /dev/null +++ b/setup/fedora/07-default-shell.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + command_exists zsh || die "zsh not found; install it via dnf first" +} + +help() { + cat <<'EOF' +Change the default shell to zsh if not already set. +Idempotent: skips when zsh is already the default shell. +EOF +} + +run() { + ensure_default_shell_zsh +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/08-zsh-plugins.sh b/setup/fedora/08-zsh-plugins.sh new file mode 100755 index 0000000..8613413 --- /dev/null +++ b/setup/fedora/08-zsh-plugins.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + require_command git +} + +help() { + cat <<'EOF' +Clone ZSH plugins (zsh-autosuggestions, zsh-syntax-highlighting, +zsh-autocomplete) into ~/.zsh/. Idempotent: skips existing directories. +EOF +} + +run() { + log "Installing ZSH plugins..." + install_zsh_plugins +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/09-tealdeer.sh b/setup/fedora/09-tealdeer.sh new file mode 100755 index 0000000..98ecb12 --- /dev/null +++ b/setup/fedora/09-tealdeer.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + require_command mkdir +} + +help() { + cat <<'EOF' +Create tealdeer config directory and update tldr cache. +Idempotent: directory creation is a no-op when it exists; tldr --update is +safe to re-run. +EOF +} + +run() { + setup_tealdeer +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/10-jetbrains-toolbox.sh b/setup/fedora/10-jetbrains-toolbox.sh new file mode 100755 index 0000000..78a1d3e --- /dev/null +++ b/setup/fedora/10-jetbrains-toolbox.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +JETBRAINS_VERSION="3.0.1.59888" +BASE_DIR="$HOME/.config/jetbrains" +ARCHIVE="$BASE_DIR/jetbrains-toolbox-$JETBRAINS_VERSION.tar.gz" +UNPACKED="$BASE_DIR/jetbrains-toolbox-$JETBRAINS_VERSION" +BIN="$UNPACKED/bin/jetbrains-toolbox" + +presteps() { + require_command wget + require_command tar +} + +help() { + cat <<'EOF' +Download and extract JetBrains Toolbox. Does NOT launch it (unlike the old +script). Idempotent: skips when the toolbox binary already exists. +EOF +} + +run() { + if [[ -x "$BIN" ]]; then + log "JetBrains Toolbox already installed at $BIN" + return 0 + fi + + log "Downloading JetBrains Toolbox $JETBRAINS_VERSION..." + ensure_dir "$BASE_DIR" + wget -q -O "$ARCHIVE" "https://download.jetbrains.com/toolbox/jetbrains-toolbox-$JETBRAINS_VERSION.tar.gz" + tar -xzf "$ARCHIVE" -C "$BASE_DIR" + log "JetBrains Toolbox extracted to $UNPACKED" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/11-proton-bridge.sh b/setup/fedora/11-proton-bridge.sh new file mode 100755 index 0000000..73f4ad3 --- /dev/null +++ b/setup/fedora/11-proton-bridge.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +PROTON_RPM="protonmail-bridge-3.13.0-1.x86_64.rpm" +PROTON_URL="https://proton.me/download/bridge/$PROTON_RPM" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" + require_command wget + require_command dnf +} + +help() { + cat <<'EOF' +Download and install Proton Mail Bridge RPM. +Idempotent: skips when the package is already installed (checked via rpm -q). +EOF +} + +run() { + if rpm -q protonmail-bridge >/dev/null 2>&1; then + log "Proton Mail Bridge already installed." + return 0 + fi + + local tmpdir + tmpdir="$(mktemp -d)" + trap 'rm -rf "$tmpdir"' RETURN + + log "Downloading Proton Mail Bridge..." + wget -q -P "$tmpdir" "$PROTON_URL" + sudo dnf install -y "$tmpdir/$PROTON_RPM" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/12-bun.sh b/setup/fedora/12-bun.sh new file mode 100755 index 0000000..be3844c --- /dev/null +++ b/setup/fedora/12-bun.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command curl +} + +help() { + cat <<'EOF' +Install Bun via the official installer script. +Idempotent: skips when `bun` is already on PATH. +EOF +} + +run() { + if command_exists bun; then + log "Bun already installed ($(bun --version 2>/dev/null || true))." + return 0 + fi + log "Installing Bun..." + curl -fsSL https://bun.com/install | bash +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/13-junie.sh b/setup/fedora/13-junie.sh new file mode 100755 index 0000000..dd45c1c --- /dev/null +++ b/setup/fedora/13-junie.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command curl +} + +help() { + cat <<'EOF' +Install Junie CLI via the official installer script. +Idempotent: skips when `junie` is already on PATH. +EOF +} + +run() { + if command_exists junie; then + log "Junie already installed." + return 0 + fi + log "Installing Junie..." + curl -fsSL https://junie.jetbrains.com/install.sh | bash +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/14-tailscale.sh b/setup/fedora/14-tailscale.sh new file mode 100755 index 0000000..e2f3112 --- /dev/null +++ b/setup/fedora/14-tailscale.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + [[ -f /etc/fedora-release ]] || die "this step requires Fedora" +} + +help() { + cat <<'EOF' +Enable and start Tailscale, and set the current user as operator. +Idempotent: systemctl enable --now is safe on already-running services; +tailscale set --operator is safe to re-run. +EOF +} + +run() { + log "Enabling Tailscale..." + sudo systemctl enable --now tailscaled 2>/dev/null || log "warn: tailscaled service setup failed (may be expected in containers)" + sudo tailscale set --operator="$USER" 2>/dev/null || log "warn: tailscale operator setup failed (may be expected in containers)" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/15-starship.sh b/setup/fedora/15-starship.sh new file mode 100755 index 0000000..3748eb6 --- /dev/null +++ b/setup/fedora/15-starship.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command curl +} + +help() { + cat <<'EOF' +Install Starship prompt via the official installer script. +Idempotent: skips when `starship` is already on PATH. +EOF +} + +run() { + if command_exists starship; then + log "Starship already installed ($(starship --version 2>/dev/null || true))." + return 0 + fi + log "Installing Starship..." + curl -sS https://starship.rs/install.sh | sh -s -- -y +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/fedora/common.bash b/setup/fedora/common.bash new file mode 100644 index 0000000..76fe7e2 --- /dev/null +++ b/setup/fedora/common.bash @@ -0,0 +1,105 @@ +#!/usr/bin/env bash +# Fedora-specific helper library for setup steps. +# +# Sourced by Fedora step scripts via: +# source "$SCRIPT_DIR/common.bash" +# This file is NOT executable — the runner does not discover it as a step. +# +# Contains dnf, COPR, Flatpak, service, and Fedora-specific installer/downloader +# guards. Platform-neutral primitives live in setup/general/common.bash. + +[[ -n "${_SETUP_FEDORA_COMMON:-}" ]] && return 0 +_SETUP_FEDORA_COMMON=1 + +# Source general helpers if not already sourced. +if [[ -z "${_SETUP_GENERAL_COMMON:-}" ]]; then + # shellcheck source=../general/common.bash + source "$REPO_DIR/setup/general/common.bash" +fi + +# Install dnf packages from a manifest file (one package per line, # comments). +# Uses `dnf install -y` which is a no-op for already-installed packages. +dnf_install_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + local packages=() + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + packages+=("$pkg") + done < "$file" + + [[ ${#packages[@]} -gt 0 ]] || { log "no packages in $file"; return 0; } + sudo dnf install -y "${packages[@]}" +} + +# Enable COPR repos from a manifest file. Checks if already enabled first. +enable_copr_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + while IFS= read -r repo; do + [[ -z "$repo" || "$repo" =~ ^[[:space:]]*# ]] && continue + if dnf copr list --enabled 2>/dev/null | grep -qF "$repo"; then + log "COPR already enabled: $repo" + continue + fi + log "Enabling COPR: $repo" + sudo dnf copr enable -y "$repo" + done < "$file" +} + +# Ensure Flatpak is installed and Flathub remote exists. Idempotent. +ensure_flatpak_runtime() { + command_exists flatpak || sudo dnf install -y flatpak + + if flatpak remote-list 2>/dev/null | grep -qi flathub; then + log "Flathub remote already exists." + return 0 + fi + log "Adding Flathub remote..." + sudo flatpak remote-add --if-not-exists flathub https://flathub.org/repo/flathub.flatpakrepo +} + +# Install Flatpak apps from a manifest file. Skips already-installed apps. +flatpak_install_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + while IFS= read -r app; do + [[ -z "$app" || "$app" =~ ^[[:space:]]*# ]] && continue + if flatpak list --app 2>/dev/null | grep -qF "$app"; then + log "Flatpak already installed: $app" + continue + fi + log "Installing Flatpak: $app" + flatpak install -y flathub "$app" || log "warn: flatpak failed/skipped: $app" + done < "$file" +} + +# Change default shell to zsh if not already set. Idempotent. +ensure_default_shell_zsh() { + if [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then + log "Default shell is already zsh." + return 0 + fi + log "Changing default shell to zsh..." + chsh -s "$(command -v zsh)" || log "warn: chsh failed (may be expected in containers)" +} + +# Install ZSH plugins via git clone. Idempotent: skips existing directories. +install_zsh_plugins() { + ensure_dir "$HOME/.zsh" + + ensure_git_clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" + ensure_git_clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" + ensure_git_clone https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" +} + +# Create tealdeer config dir and update tldr cache. Idempotent. +setup_tealdeer() { + ensure_dir "$HOME/.config/tealdeer" + if command_exists tldr; then + tldr --update 2>/dev/null || true + fi +} \ No newline at end of file diff --git a/setup/fedora/copr.txt b/setup/fedora/copr.txt new file mode 100644 index 0000000..3990d3b --- /dev/null +++ b/setup/fedora/copr.txt @@ -0,0 +1,2 @@ +atim/lazygit +zeno/scrcpy diff --git a/packages/fedora/dnf.txt b/setup/fedora/dnf.txt similarity index 99% rename from packages/fedora/dnf.txt rename to setup/fedora/dnf.txt index 41d77a8..d66a17f 100644 --- a/packages/fedora/dnf.txt +++ b/setup/fedora/dnf.txt @@ -543,6 +543,7 @@ xsel yarnpkg yelp yq +yubico-piv-tool zip zlib-ng-compat-devel zram-generator-defaults diff --git a/packages/fedora/flatpak.txt b/setup/fedora/flatpak.txt similarity index 100% rename from packages/fedora/flatpak.txt rename to setup/fedora/flatpak.txt diff --git a/setup/general/01-symlinks.sh b/setup/general/01-symlinks.sh new file mode 100755 index 0000000..b2aec96 --- /dev/null +++ b/setup/general/01-symlinks.sh @@ -0,0 +1,61 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command ln + require_command mkdir +} + +help() { + cat <<'EOF' +Symlink dotfiles (zshrc, vimrc, gitconfig, vim/, nvim/, lazygit/, junie/, +kitty/, ghostty/, Nextcloud/, ssh config) into $HOME. Idempotent: existing correct +symlinks are left untouched; pre-existing non-symlinks are backed up once. +EOF +} + +run() { + log "Setting up symlinks..." + + ensure_dir "$HOME/.config" + # ensure_dir "$HOME/.ssh" + + ensure_symlink "$REPO_DIR/zshrc" "$HOME/.zshrc" + ensure_symlink "$REPO_DIR/vimrc" "$HOME/.vimrc" + ensure_symlink "$REPO_DIR/gitconfig" "$HOME/.gitconfig" + ensure_symlink "$REPO_DIR/starship.toml" "$HOME/.config/starship.toml" + + ensure_symlink "$REPO_DIR/vim" "$HOME/.vim" + ensure_symlink "$REPO_DIR/nvim" "$HOME/.config/nvim" + ensure_symlink "$REPO_DIR/lazygit" "$HOME/.config/lazygit" + ensure_symlink "$REPO_DIR/ssh" "$HOME/.ssh" + + ensure_symlink "$REPO_DIR/junie" "$HOME/.junie" + + [[ -d "$REPO_DIR/kitty" ]] && ensure_symlink "$REPO_DIR/kitty" "$HOME/.config/kitty" + [[ -d "$REPO_DIR/ghostty" ]] && ensure_symlink "$REPO_DIR/ghostty" "$HOME/.config/ghostty" + [[ -d "$REPO_DIR/Nextcloud" ]] && ensure_symlink "$REPO_DIR/Nextcloud" "$HOME/.config/Nextcloud" + + # [[ -f "$REPO_DIR/ssh/config" ]] && ensure_symlink "$REPO_DIR/ssh/config" "$HOME/.ssh/config" + # [[ -f "$REPO_DIR/ssh/known_hosts" ]] && ensure_symlink "$REPO_DIR/ssh/known_hosts" "$HOME/.ssh/known_hosts" + + if [[ ! -L "$HOME/.ssh" ]]; then + chmod 700 "$HOME/.ssh" || true + fi +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/setup/general/02-git-filters.sh b/setup/general/02-git-filters.sh new file mode 100755 index 0000000..7c7b907 --- /dev/null +++ b/setup/general/02-git-filters.sh @@ -0,0 +1,71 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command git + require_command mktemp + require_command cmp +} + +help() { + cat <<'EOF' +Register git clean/smudge filters for this dotfiles repo: pkcs11-provider +(tokenizes/resolves SSH PKCS#11 provider paths) and scrub-apikey (redacts API +keys in junie model configs). Idempotent: filters are only rewritten when the +configured value differs. +EOF +} + +run() { + log "Configuring git filters..." + + ensure_git_config filter.pkcs11-provider.clean "ssh/pkcs11-filter.sh clean" + ensure_git_config filter.pkcs11-provider.smudge "ssh/pkcs11-filter.sh smudge" + ensure_git_config filter.pkcs11-provider.required true + + ensure_git_config filter.scrub-apikey.clean \ + "sed -E 's/(\"apiKey\"[[:space:]]*:[[:space:]]*)\"[^\"]*\"/\\1\"REDACTED\"/'" + ensure_git_config filter.scrub-apikey.smudge cat + ensure_git_config filter.scrub-apikey.required true + + if git rev-parse --is-inside-work-tree >/dev/null 2>&1; then + while IFS= read -r -d '' file; do + git update-index --refresh -- "$file" >/dev/null 2>&1 || true + if git diff --quiet -- "$file"; then + tmpfile="$(mktemp "$REPO_DIR/.pkcs11-filter.XXXXXX")" + cp -p "$REPO_DIR/$file" "$tmpfile" + if git show ":$file" | "$REPO_DIR/ssh/pkcs11-filter.sh" smudge > "$tmpfile"; then + if cmp -s "$tmpfile" "$REPO_DIR/$file"; then + rm -f "$tmpfile" + else + mv "$tmpfile" "$REPO_DIR/$file" + git update-index --refresh -- "$file" >/dev/null 2>&1 || true + fi + else + rm -f "$tmpfile" + return 1 + fi + else + log "skip: modified git-filtered file: $file" + fi + done < <(git ls-files -z -- 'ssh/config.d/*') + fi + + log "Git filters configured: pkcs11-provider, scrub-apikey" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/setup/general/03-vim-base.sh b/setup/general/03-vim-base.sh new file mode 100755 index 0000000..f7a3e32 --- /dev/null +++ b/setup/general/03-vim-base.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command mkdir +} + +help() { + cat <<'EOF' +Create OS-agnostic editor support directories such as $HOME/.vim/undo. Theme +downloads and platform-specific editor setup remain in OS-specific steps. +EOF +} + +run() { + log "Creating shared editor directories..." + ensure_dir "$HOME/.vim/undo" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/setup/general/common.bash b/setup/general/common.bash new file mode 100644 index 0000000..3eff39a --- /dev/null +++ b/setup/general/common.bash @@ -0,0 +1,103 @@ +#!/usr/bin/env bash +# Shared platform-neutral helper library for setup steps. +# +# Sourced by step scripts via: source "$REPO_DIR/setup/general/common.bash" +# This file is NOT executable on purpose, so the runner does not discover it as +# a step. +# +# It contains ONLY OS-agnostic primitives. Flatpak, package-manager +# (brew/dnf/pacman/rpm-ostree/yay), installer/downloader, GUI app, and +# service/shell mutation logic MUST NOT live here — keep those in the relevant +# setup// directory or its own common.bash companion. + +# Guard against double-sourcing. +[[ -n "${_SETUP_GENERAL_COMMON:-}" ]] && return 0 +_SETUP_GENERAL_COMMON=1 + +log() { + printf '%s\n' "$*" +} + +die() { + printf 'error: %s\n' "$*" >&2 + exit 1 +} + +command_exists() { + command -v "$1" >/dev/null 2>&1 +} + +require_command() { + local cmd="$1" + command_exists "$cmd" || die "required command not found: $cmd" +} + +# Read a manifest file, skipping blank and comment lines. +read_manifest() { + local file="$1" + [[ -f "$file" ]] || return 0 + grep -vE '^[[:space:]]*$|^[[:space:]]*#' "$file" +} + +ensure_dir() { + local dir="$1" + [[ -d "$dir" ]] || mkdir -p "$dir" +} + +# Idempotent symlink: create dest -> src, backing up an existing non-symlink +# once with a timestamped name. If dest is already the correct symlink, no-op. +ensure_symlink() { + local src="$1" + local dest="$2" + + [[ -e "$src" ]] || { log "skip: source does not exist: $src"; return 0; } + + ensure_dir "$(dirname "$dest")" + + if [[ -L "$dest" ]]; then + if [[ "$(readlink "$dest")" == "$src" ]]; then + return 0 + fi + ln -sfn "$src" "$dest" + log "linked: $dest -> $src" + return 0 + fi + + if [[ -e "$dest" ]]; then + local backup="${dest}.bak.$(date +%Y%m%d%H%M%S)" + mv "$dest" "$backup" + log "backup: $dest -> $backup" + fi + + ln -sfn "$src" "$dest" + log "linked: $dest -> $src" +} + +# Set a git config key/value idempotently. Writes to the local repo config when +# run inside a git repo, otherwise global. Only writes when the value differs. +ensure_git_config() { + local key="$1" + local value="$2" + local current + current="$(git config "$key" 2>/dev/null || true)" + [[ "$current" == "$value" ]] && return 0 + git config "$key" "$value" +} + +# Clone a git repo if absent; never re-clone or force-update an existing one. +ensure_git_clone() { + local url="$1" + local dest="$2" + [[ -d "$dest/.git" ]] && return 0 + ensure_dir "$(dirname "$dest")" + git clone "$url" "$dest" +} + +# Ensure a line is present in a text file, appending if absent. Creates the +# file (and parent dir) if needed. +ensure_line_present() { + local file="$1" + local line="$2" + [[ -f "$file" ]] || { ensure_dir "$(dirname "$file")"; : > "$file"; } + grep -qxF -- "$line" "$file" || printf '%s\n' "$line" >> "$file" +} diff --git a/setup/macos/01-homebrew.sh b/setup/macos/01-homebrew.sh new file mode 100755 index 0000000..f468b86 --- /dev/null +++ b/setup/macos/01-homebrew.sh @@ -0,0 +1,34 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" +} + +help() { + cat <<'EOF' +Install Homebrew if not already present. Idempotent: skips when brew is on PATH. +EOF +} + +run() { + ensure_homebrew +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/macos/02-brew-bundle.sh b/setup/macos/02-brew-bundle.sh new file mode 100755 index 0000000..650f077 --- /dev/null +++ b/setup/macos/02-brew-bundle.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +BREWFILE="$SCRIPT_DIR/Brewfile" + +presteps() { + require_command brew + [[ -f "$BREWFILE" ]] || die "Brewfile not found: $BREWFILE" +} + +help() { + cat <<'EOF' +Install Homebrew packages from setup/macos/Brewfile via `brew bundle`. +Idempotent: brew bundle is a no-op for already-installed packages. +EOF +} + +run() { + log "Installing Homebrew packages from Brewfile..." + brew bundle --file="$BREWFILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/macos/03-ssh-agent.sh b/setup/macos/03-ssh-agent.sh new file mode 100755 index 0000000..db6db40 --- /dev/null +++ b/setup/macos/03-ssh-agent.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" +} + +help() { + cat <<'EOF' +Start ssh-agent if not already running. Idempotent: skips when a user +ssh-agent process is already found. +EOF +} + +run() { + ensure_ssh_agent +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/macos/04-ssh-keychain.sh b/setup/macos/04-ssh-keychain.sh new file mode 100755 index 0000000..4ca1a2a --- /dev/null +++ b/setup/macos/04-ssh-keychain.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" + require_command ssh-add +} + +help() { + cat <<'EOF' +Add private SSH keys (~/.ssh/*, mode 0600, excluding .pub/known_hosts/config) +to the Apple keychain via `ssh-add --apple-use-keychain`. Idempotent: keys +already in the agent are not re-added (ssh-add handles this natively). +EOF +} + +run() { + local ssh_dir="$HOME/.ssh" + [[ -d "$ssh_dir" ]] || { log "no ~/.ssh directory; skipping."; return 0; } + + local added=0 + while IFS= read -r -d '' key; do + case "$(basename "$key")" in + *.pub|known_hosts|config) continue ;; + esac + log "Adding SSH key to Apple keychain: $key" + ssh-add --apple-use-keychain "$key" >/dev/null 2>&1 || true + added=$((added + 1)) + done < <(find "$ssh_dir" -type f -perm 600 -print0 2>/dev/null) + + log "Processed $added SSH key(s)." +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/macos/05-vim-theme.sh b/setup/macos/05-vim-theme.sh new file mode 100755 index 0000000..2ee0251 --- /dev/null +++ b/setup/macos/05-vim-theme.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +THEME_DIR="$HOME/.vim/pack/themes/start/dracula" + +presteps() { + require_command git +} + +help() { + cat <<'EOF' +Clone the Dracula vim theme into ~/.vim/pack/themes/start/dracula. +Idempotent: skips when the theme directory already exists. +EOF +} + +run() { + if [[ -d "$THEME_DIR" ]]; then + log "Dracula vim theme already installed." + return 0 + fi + log "Installing Dracula vim theme..." + ensure_dir "$(dirname "$THEME_DIR")" + git clone https://github.com/dracula/vim.git "$THEME_DIR" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/macos/06-junie.sh b/setup/macos/06-junie.sh new file mode 100755 index 0000000..9661778 --- /dev/null +++ b/setup/macos/06-junie.sh @@ -0,0 +1,44 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" +} + +help() { + cat <<'EOF' +Install Junie CLI via the official curl installer. Idempotent: skips when junie +is already on PATH. +EOF +} + +run() { + if command_exists junie; then + log "Junie CLI already installed ($(junie --version 2>/dev/null || true))." + return 0 + fi + + log "Installing Junie CLI..." + curl -fsSL https://junie.jetbrains.com/install.sh | bash + + command_exists junie || die "Junie CLI installation finished but junie is still not on PATH" + log "Junie CLI installed ($(junie --version 2>/dev/null || true))." +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/setup/macos/07-waveforms.sh b/setup/macos/07-waveforms.sh new file mode 100755 index 0000000..cd0023d --- /dev/null +++ b/setup/macos/07-waveforms.sh @@ -0,0 +1,215 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +WAVEFORMS_VERSION="3.25.1" +WAVEFORMS_URL="https://files.digilent.com/Software/Waveforms/${WAVEFORMS_VERSION}/digilent.waveforms_v${WAVEFORMS_VERSION}.dmg" +WAVEFORMS_NEWER_URL="https://cloud.digilent.com/myproducts/waveforms?pc=1&tab=2" +WAVEFORMS_DMG_NAME="digilent.waveforms_v${WAVEFORMS_VERSION}.dmg" +APP_PATH="/Applications/WaveForms.app" + +# Browser-like headers. files.digilent.com sits behind Cloudflare, which serves +# a JS "managed challenge" to non-browser clients (curl gets HTTP 403 even though +# the same URL downloads fine in Chrome/Firefox/Safari). These headers let curl +# through when Cloudflare is not challenging; otherwise we fall back to the +# default browser (see download_via_browser). +CURL_BROWSER_HEADERS=( + -H 'User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36' + -H 'Accept: text/html,application/xhtml+xml,application/xml;q=0.9,application/octet-stream;q=0.9,*/*;q=0.8' + -H 'Accept-Language: en-US,en;q=0.5' + -H 'Accept-Encoding: gzip, deflate, br' + -H 'Upgrade-Insecure-Requests: 1' + -H 'Sec-Fetch-Dest: document' + -H 'Sec-Fetch-Mode: navigate' + -H 'Sec-Fetch-Site: none' + -H 'Sec-Fetch-User: ?1' +) + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" + require_command curl + require_command hdiutil + require_command open +} + +help() { + cat <<'EOF' +Download and install Digilent WaveForms from the official .dmg release. Not +installed via the Brewfile because the cask is not kept up to date on Homebrew. +Idempotent: skips when WaveForms.app is already in /Applications. + +files.digilent.com is behind Cloudflare, which blocks plain curl with HTTP 403 +(a JS challenge). The script first tries curl with browser-like headers; if that +is challenged it opens the URL in the default browser (where it downloads fine) +and then installs the .dmg once it lands in ~/Downloads. +EOF +} + +# Returns 0 if $1 looks like a real Apple disk image rather than a Cloudflare +# challenge / error HTML page served with HTTP 200. +is_real_dmg() { + local file="$1" + [[ -s "$file" ]] || return 1 + # Cloudflare challenge pages are HTML starting with "". + head -c 64 "$file" | grep -qi '/dev/null || true)" + case "$kind" in + *Apple\ Disk\ Image*|*zlib\ compressed\ data*|*data*) return 0 ;; + *HTML*|*ASCII*|*UTF-8*|*text*) return 1 ;; + *) return 0 ;; + esac +} + +# Try curl with browser-like headers. Sets WAVEFORMS_DMG_PATH to the +# downloaded dmg path and returns 0 on success, or returns non-zero on +# failure / Cloudflare challenge. +download_via_curl() { + local out="$1" + log "Trying curl with browser headers..." + if curl -fsSL "${CURL_BROWSER_HEADERS[@]}" -o "$out" "$WAVEFORMS_URL" \ + && is_real_dmg "$out"; then + WAVEFORMS_DMG_PATH="$out" + return 0 + fi + rm -f "$out" + return 1 +} + +# Cloudflare blocks curl, so hand the URL to the default browser (where it +# downloads fine) and wait for the .dmg to land in ~/Downloads. Sets +# WAVEFORMS_DMG_PATH to the downloaded dmg path on success. +download_via_browser() { + local downloads_dir="${HOME}/Downloads" + local expected="${downloads_dir}/${WAVEFORMS_DMG_NAME}" + + # If a previous browser download is already there, reuse it. + if [[ -f "$expected" ]] && is_real_dmg "$expected"; then + log "Found existing download: $expected" + WAVEFORMS_DMG_PATH="$expected" + return 0 + fi + # A stale/bad file (e.g. a Cloudflare HTML page saved earlier) would make the + # wait loop below never see a real dmg — remove it so the browser can replace it. + if [[ -f "$expected" ]]; then + log "Removing stale/invalid file at $expected" + rm -f "$expected" + fi + + log "Cloudflare blocked the curl download (HTTP 403 / JS challenge)." + log "Opening the URL in your default browser — please save the .dmg:" + log " ${WAVEFORMS_URL}" + open "$WAVEFORMS_URL" + + log "Waiting for ${WAVEFORMS_DMG_NAME} to appear in ${downloads_dir}..." + local waited=0 + local prev_size=-1 stable=0 + while (( waited < 600 )); do + sleep 5 + waited=$((waited + 5)) + + # Browsers download to a partial file (e.g. *.dmg.download / *.crdownload) + # first; only consider the final name once it exists. + if [[ ! -f "$expected" ]]; then + continue + fi + + local size + size="$(stat -f%z "$expected" 2>/dev/null || echo 0)" + if [[ "$size" -eq 0 ]]; then + continue + fi + if [[ "$size" -eq "$prev_size" ]]; then + stable=$((stable + 1)) + else + stable=0 + prev_size="$size" + fi + + # Treat the download as complete once the size stops changing for ~10s and + # the file is a real disk image. + if (( stable >= 2 )) && is_real_dmg "$expected"; then + log "Download complete: $expected" + WAVEFORMS_DMG_PATH="$expected" + return 0 + fi + done + + die "timed out waiting for ${WAVEFORMS_DMG_NAME} in ${downloads_dir}" +} + +install_dmg() { + local dmg="$1" + local mount_point + mount_point="$(mktemp -d -t waveforms.XXXXXX)" + + log "Mounting $dmg..." + hdiutil attach -nobrowse -readonly -mountpoint "$mount_point" "$dmg" >/dev/null + + local app_src + app_src="$(find "$mount_point" -maxdepth 1 -name 'WaveForms.app' -print -quit)" + [[ -n "$app_src" ]] || { hdiutil detach "$mount_point" >/dev/null; die "WaveForms.app not found in mounted dmg"; } + + log "Installing $app_src -> /Applications" + cp -R "$app_src" /Applications/ + + hdiutil detach "$mount_point" >/dev/null +} + +run() { + log "" + log "=== Digilent WaveForms ===" + + if [[ -d "$APP_PATH" ]]; then + log "WaveForms already installed at $APP_PATH" + log "Newer versions or other platforms (login required): $WAVEFORMS_NEWER_URL" + return 0 + fi + + local dmg="" + local tmp_dmg + tmp_dmg="$(mktemp -t waveforms.XXXXXX).dmg" + + WAVEFORMS_DMG_PATH="" + if download_via_curl "$tmp_dmg"; then + : + else + log "curl download failed or was blocked by Cloudflare." + download_via_browser || die "no WaveForms .dmg available to install" + fi + + dmg="$WAVEFORMS_DMG_PATH" + [[ -n "$dmg" && -f "$dmg" ]] || die "no WaveForms .dmg available to install" + is_real_dmg "$dmg" || die "downloaded file is not a valid .dmg: $dmg" + + install_dmg "$dmg" + + # Only clean up the temp curl download; keep the browser-downloaded file in + # ~/Downloads so the user can re-run/reinstall without re-downloading. + case "$dmg" in + "$tmp_dmg") rm -f "$dmg" ;; + esac + + log "WaveForms installed at $APP_PATH" + log "Newer versions or other platforms (login required): $WAVEFORMS_NEWER_URL" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/setup/macos/08-kitty-permissions.sh b/setup/macos/08-kitty-permissions.sh new file mode 100755 index 0000000..eb3b54b --- /dev/null +++ b/setup/macos/08-kitty-permissions.sh @@ -0,0 +1,48 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +FULL_DISK_ACCESS_URL="x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles" +LOCAL_NETWORK_URL="x-apple.systempreferences:com.apple.preference.security?Privacy_LocalNetwork" + +presteps() { + [[ "$(uname -s)" == "Darwin" ]] || die "this step requires macOS" + require_command open +} + +help() { + cat <<'EOF' +Open macOS Privacy & Security settings so Kitty can be granted Full Disk Access +and Local Network access. macOS requires these permissions to be enabled by the +user; the step cannot grant them automatically. +EOF +} + +run() { + log "Opening Full Disk Access settings for Kitty..." + open "$FULL_DISK_ACCESS_URL" + + log "Opening Local Network settings for Kitty..." + open "$LOCAL_NETWORK_URL" + + log "In Full Disk Access, add /Applications/kitty.app and enable it." + log "In Local Network, enable Kitty if it is listed." + log "Restart Kitty for the changes to take effect." +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac diff --git a/packages/macos/Brewfile b/setup/macos/Brewfile similarity index 73% rename from packages/macos/Brewfile rename to setup/macos/Brewfile index 6c10308..f57ca12 100644 --- a/packages/macos/Brewfile +++ b/setup/macos/Brewfile @@ -1,7 +1,9 @@ +tap "can1357/tap" tap "finestructure/tap" tap "grishka/grishka" tap "homebrew-ffmpeg/ffmpeg", trusted: true tap "jetbrains/junie", trusted: true +tap "jundot/omlx", "https://github.com/jundot/omlx" tap "nikitabobko/tap" # Cryptography and SSL/TLS Toolkit brew "openssl@3" @@ -79,8 +81,8 @@ brew "libtool" brew "graphviz" # GNU grep, egrep and fgrep brew "grep" -# Low-level access to audio, keyboard, mouse, joystick, and graphics -brew "sdl2" +# SDL2 compatibility layer that uses SDL3 behind the scenes +brew "sdl2-compat" # Play, record, convert, and stream select audio and video codecs brew "ffmpeg", args: ["with-webp", "with-xvid"] # GNOME Python bindings (based on GObject Introspection) @@ -89,12 +91,12 @@ brew "pygobject3" brew "gstreamer" # C/C++ and Java libraries for Unicode and globalization brew "icu4c@76" +# C/C++ and Java libraries for Unicode and globalization +brew "icu4c@77" # Tools and libraries to manipulate images in select formats brew "imagemagick" # Cross-platform Java Version Manager brew "jabba" -# Interpreted, interactive, object-oriented programming language -brew "python@3.13" # Sane PBXProj files brew "kin" # Anti-bikeshedding Kotlin linter with built-in formatter @@ -111,12 +113,12 @@ brew "libslirp" brew "ltex-ls-plus" # Utility for directing compilation brew "make" +# Command-line utility to communicate with ModBus slave (RTU or TCP) +brew "mbpoll" # Simple tool to make locally trusted development certificates brew "mkcert" # Message broker implementing the MQTT protocol brew "mosquitto" -# General-purpose lossless data-compression library -brew "zlib" # Open source relational database management system brew "mysql-client" # Ambitious Vim-fork focused on extensibility and agility @@ -132,7 +134,13 @@ brew "nss" # Manage multiple Node.js versions brew "nvm" # Development kit for the Java programming language +brew "openjdk@17" +# Development kit for the Java programming language brew "openjdk@21" +# Tools and libraries for smart cards +brew "opensc" +# OpenBSD freely-licensed SSH connectivity tools +brew "openssh" # Cryptography and SSL/TLS Toolkit brew "openssl@1.1" # Minimal dumb-terminal emulation program @@ -149,6 +157,8 @@ brew "podman-compose" brew "pulseaudio" # Python version management brew "pyenv" +# Interpreted, interactive, object-oriented programming language +brew "python@3.13" # Generic machine emulator and virtualizer brew "qemu" # Search tool like grep and The Silver Searcher @@ -165,6 +175,8 @@ brew "skopeo" brew "socat" # Audio processing library brew "sound-touch" +# Cross-shell prompt for astronauts +brew "starship" # Tool to enforce Swift style and conventions brew "swiftlint" # Easiest, most secure way to use WireGuard and 2FA @@ -179,6 +191,12 @@ brew "tree" brew "wget" # JavaScript package manager brew "yarn" +# Tool for managing your YubiKey configuration +brew "ykman" +# Command-line tool for the YubiKey PIV application +brew "yubico-piv-tool" +# General-purpose lossless data-compression library +brew "zlib" # Real-time type-ahead completion for Zsh brew "zsh-autocomplete" # Fish-like fast/unobtrusive autosuggestions for zsh @@ -187,18 +205,16 @@ brew "zsh-autosuggestions" brew "zsh-syntax-highlighting" # Play, record, convert, and stream audio and video brew "homebrew-ffmpeg/ffmpeg/ffmpeg", args: ["with-webp", "with-xvid"] -# Junie CLI -brew "jetbrains/junie/junie" # Android SDK component cask "android-platform-tools" -# Network scanner -cask "angry-ip-scanner" # Electronics prototyping platform cask "arduino-ide" # Utility improving 3rd party mouse performance and functionalities cask "bettermouse" # Web security testing toolkit cask "burp-suite" +# Slicer and cloud services for some Creality FDM 3D printers +cask "creality-print" # Visually compare and merge files cask "diffmerge" # Collaborative team software @@ -211,22 +227,16 @@ cask "freecad" cask "google-chrome" # Hex editor for reverse engineers cask "imhex" -# Terminal emulator as alternative to Apple's Terminal app -cask "iterm2" # JetBrains tools manager cask "jetbrains-toolbox" -# CAD application -cask "librecad" -# Privacy-first, open-source platform for knowledge sharing and management -cask "logseq" +# GPU-based terminal emulator +cask "kitty" # Connect to your Android devices cask "macdroid" # Full TeX Live distribution with GUI applications cask "mactex" # Mesh processing system cask "meshlab" -# Meet, chat, call, and collaborate in just one place -cask "microsoft-teams" cask "mqtt-explorer" # Desktop sync client for Nextcloud software products cask "nextcloud-vfs" @@ -240,6 +250,8 @@ cask "openscad" cask "postman" # Client for Proton Drive cask "proton-drive" +# Bridges Proton Mail to email clients supporting IMAP and SMTP protocols +cask "proton-mail-bridge" # VPN client focusing on security cask "protonvpn" # HTTP debugging proxy @@ -252,6 +264,8 @@ cask "raspberry-pi-imager" cask "raycast" # Software and Documentation pack for Segger J-Link debug probes cask "segger-jlink" +# Software and Documentation pack for Segger Ozone J-Link debugger +cask "segger-ozone" # Team communication and collaboration software cask "slack" # Music streaming service @@ -264,8 +278,6 @@ cask "temurin@8" cask "texifier" # Customizable email client cask "thunderbird" -# Virtual machines UI using QEMU -cask "utm" # Multimedia player cask "vlc" # Binary releases of VS Code without MS branding/telemetry/licensing @@ -274,123 +286,43 @@ cask "vscodium" cask "wireshark-app" # Collect, organise, cite, and share research sources cask "zotero" -vscode "13xforever.language-x86-64-assembly" -vscode "aaron-bond.better-comments" -vscode "alefragnani.bookmarks" -vscode "alexcvzz.vscode-sqlite" -vscode "angular.ng-template" -vscode "anilkumarum.compile-ts" -vscode "anweber.httpbook" vscode "anweber.vscode-httpyac" -vscode "bbenoist.doxygen" -vscode "bierner.emojisense" -vscode "bleastprogram.cpp-compiler" -vscode "cheshirekow.cmake-format" -vscode "christian-kohler.npm-intellisense" -vscode "christian-kohler.path-intellisense" -vscode "continue.continue" -vscode "cschlosser.doxdocgen" vscode "davidanson.vscode-markdownlint" -vscode "dbaeumer.vscode-eslint" vscode "ddorch.codium-devcontainer" -vscode "devsense.composer-php-vscode" -vscode "devsense.intelli-php-vscode" -vscode "devsense.phptools-vscode" -vscode "devsense.profiler-php-vscode" vscode "dreamcatcher45.podmanager" -vscode "dsznajder.es7-react-js-snippets" -vscode "eamodio.gitlens" -vscode "eclipse-cdt.serial-monitor" vscode "efoerster.texlab" -vscode "ericsia.pythonsnippets3" vscode "esbenp.prettier-vscode" vscode "espressif.esp-idf-extension" -vscode "firefox-devtools.vscode-firefox-debug" -vscode "formulahendry.code-runner" vscode "foxundermoon.shell-format" -vscode "franneck94.c-cpp-runner" -vscode "franneck94.vscode-c-cpp-config" -vscode "franneck94.vscode-c-cpp-dev-extension-pack" -vscode "franneck94.vscode-typescript-extension-pack" -vscode "fwcd.kotlin" -vscode "gicentre.markdown-preview-enhanced-with-litvis" -vscode "gruntfuggly.todo-tree" -vscode "guyutongxue.cpp-reference" -vscode "gydunhn.javascript-essentials" -vscode "gydunhn.typescript-essentials" -vscode "gydunhn.vsc-essentials-core" vscode "hangxingliu.vscode-systemd-support" -vscode "ibm.output-colorizer" vscode "james-yu.latex-workshop" -vscode "jbenden.c-cpp-flylint" vscode "jeanp413.open-remote-ssh" vscode "jebbs.plantuml" -vscode "jeff-hykin.better-cpp-syntax" vscode "jeff-hykin.better-shellscript-syntax" vscode "jeffersonqin.latex-snippets-jeff" -vscode "jock.svg" -vscode "kotlin-darcula-syntax.kotlin-darcula-syntax" -vscode "llvm-vs-code-extensions.lldb-dap" vscode "llvm-vs-code-extensions.vscode-clangd" vscode "lordimmaculate.platformio-ide" vscode "ltex-plus.vscode-ltex-plus" vscode "mads-hartmann.bash-ide-vscode" -vscode "magicstack.magicpython" -vscode "marus25.cortex-debug" -vscode "mathiasfrohlich.kotlin" -vscode "mattpocock.ts-error-translator" -vscode "mcu-debug.debug-tracker-vscode" -vscode "mcu-debug.memory-view" -vscode "mcu-debug.peripheral-viewer" -vscode "mcu-debug.rtos-views" vscode "mjpvs.latex-previewer" -vscode "mkhl.direnv" vscode "ms-azuretools.vscode-containers" vscode "ms-azuretools.vscode-docker" -vscode "ms-python.debugpy" vscode "ms-python.python" vscode "ms-python.vscode-python-envs" vscode "ms-vscode.cmake-tools" vscode "ms-vscode.hexeditor" -vscode "ms-vscode.vscode-typescript-next" -vscode "mtxr.sqltools" -vscode "mtxr.sqltools-driver-sqlite" -vscode "oderwat.indent-rainbow" vscode "phil294.git-log--graph" vscode "philosowaffle.openapi-designer" vscode "pinage404.bash-extension-pack" -vscode "pokey.parse-tree" -vscode "postman.postman-for-vscode" -vscode "prisma.prisma-insider" -vscode "project-accelerate.shared-state-store" -vscode "rail5.bashpp" -vscode "redhat.java" vscode "redhat.vscode-xml" -vscode "redocly.openapi-vs-code" vscode "repreng.csv" -vscode "rintoj.json-organizer" -vscode "rogalmic.bash-debug" vscode "rpinski.shebang-snippets" vscode "shd101wyy.markdown-preview-enhanced" -vscode "shopify.ruby-lsp" vscode "sndst00m.vscode-native-svg-preview" vscode "sr-team.clang-tidy-sr-team-fork" -vscode "sr-team.vscode-clangd-cmake" -vscode "sr-team.vscode-cpp-file-renamer" -vscode "swiftlang.swift-vscode" -vscode "swiftstream.swiftstream" vscode "tecosaur.latex-utilities" vscode "timonwong.shellcheck" -vscode "tombonnike.vscode-status-bar-format-toggle" -vscode "tomi.xajssnippets" -vscode "tomi.xasnippets" vscode "torn4dom4n.latex-support" -vscode "twxs.cmake" -vscode "usernamehw.errorlens" -vscode "vadimcn.vscode-lldb" -vscode "vknabel.vscode-apple-swift-format" -vscode "vknabel.vscode-swiftformat" vscode "waderyan.gitblame" -vscode "xabikos.javascriptsnippets" -vscode "yoavbls.pretty-ts-errors" vscode "yzhang.markdown-all-in-one" +npm "typescript" diff --git a/setup/macos/common.bash b/setup/macos/common.bash new file mode 100644 index 0000000..5d4d796 --- /dev/null +++ b/setup/macos/common.bash @@ -0,0 +1,47 @@ +#!/usr/bin/env bash +# macOS-specific helper library for setup steps. +# +# Sourced by macOS step scripts via: +# source "$SCRIPT_DIR/common.bash" +# This file is NOT executable — the runner does not discover it as a step. +# +# Contains Homebrew, keychain, and macOS-specific installer/downloader guards. +# Platform-neutral primitives live in setup/general/common.bash. + +[[ -n "${_SETUP_MACOS_COMMON:-}" ]] && return 0 +_SETUP_MACOS_COMMON=1 + +# Source general helpers if not already sourced. +if [[ -z "${_SETUP_GENERAL_COMMON:-}" ]]; then + # shellcheck source=../general/common.bash + source "$REPO_DIR/setup/general/common.bash" +fi + +# Ensure Homebrew is installed and on PATH. Idempotent. +ensure_homebrew() { + if command_exists brew; then + log "Homebrew already installed." + return 0 + fi + + log "Installing Homebrew..." + NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" + + if [[ -x /opt/homebrew/bin/brew ]]; then + eval "$(/opt/homebrew/bin/brew shellenv)" + elif [[ -x /usr/local/bin/brew ]]; then + eval "$(/usr/local/bin/brew shellenv)" + fi + + command_exists brew || die "Homebrew installation finished but brew is still not on PATH" +} + +# Ensure ssh-agent is running for the current user. Idempotent. +ensure_ssh_agent() { + if pgrep -u "$USER" ssh-agent >/dev/null 2>&1; then + log "ssh-agent already running." + return 0 + fi + log "Starting ssh-agent..." + eval "$(ssh-agent -s)" >/dev/null +} \ No newline at end of file diff --git a/setup/manjaro/01-system-update.sh b/setup/manjaro/01-system-update.sh new file mode 100755 index 0000000..851e74f --- /dev/null +++ b/setup/manjaro/01-system-update.sh @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" + command_exists pacman || die "pacman not found" +} + +help() { + cat <<'EOF' +Update system packages via `sudo pacman -Syu --noconfirm`. +Idempotent: pacman -Syu is safe to run repeatedly. +EOF +} + +run() { + log "Updating system..." + sudo pacman -Syu --noconfirm +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/02-pacman-packages.sh b/setup/manjaro/02-pacman-packages.sh new file mode 100755 index 0000000..9c4d3e4 --- /dev/null +++ b/setup/manjaro/02-pacman-packages.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +PACMAN_FILE="$SCRIPT_DIR/pacman.txt" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" + command_exists pacman || die "pacman not found" +} + +help() { + cat <<'EOF' +Install pacman packages listed in setup/manjaro/pacman.txt. +Idempotent: pacman -S --needed skips already-installed packages. +EOF +} + +run() { + log "Installing pacman packages..." + pacman_install_from_manifest "$PACMAN_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/03-yay-bootstrap.sh b/setup/manjaro/03-yay-bootstrap.sh new file mode 100755 index 0000000..f97ed8c --- /dev/null +++ b/setup/manjaro/03-yay-bootstrap.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" + require_command git +} + +help() { + cat <<'EOF' +Bootstrap yay (AUR helper) if not already installed. +Idempotent: skips when yay is already on PATH. +EOF +} + +run() { + ensure_yay +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/04-aur-packages.sh b/setup/manjaro/04-aur-packages.sh new file mode 100755 index 0000000..5a4dbea --- /dev/null +++ b/setup/manjaro/04-aur-packages.sh @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +AUR_FILE="$SCRIPT_DIR/aur.txt" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" + command_exists yay || die "yay not found; run 03-yay-bootstrap first" +} + +help() { + cat <<'EOF' +Install AUR packages listed in setup/manjaro/aur.txt via yay. +Idempotent: yay -S --needed skips already-installed packages. +EOF +} + +run() { + log "Installing AUR packages..." + aur_install_from_manifest "$AUR_FILE" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/05-default-shell.sh b/setup/manjaro/05-default-shell.sh new file mode 100755 index 0000000..0d09b13 --- /dev/null +++ b/setup/manjaro/05-default-shell.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" +} + +help() { + cat <<'EOF' +Change the default shell to zsh if not already set. +Idempotent: skips when zsh is already the default shell. +EOF +} + +run() { + ensure_default_shell_zsh +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/06-zsh-plugins.sh b/setup/manjaro/06-zsh-plugins.sh new file mode 100755 index 0000000..8613413 --- /dev/null +++ b/setup/manjaro/06-zsh-plugins.sh @@ -0,0 +1,36 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" +# shellcheck source=common.bash +source "$SCRIPT_DIR/common.bash" + +presteps() { + require_command git +} + +help() { + cat <<'EOF' +Clone ZSH plugins (zsh-autosuggestions, zsh-syntax-highlighting, +zsh-autocomplete) into ~/.zsh/. Idempotent: skips existing directories. +EOF +} + +run() { + log "Installing ZSH plugins..." + install_zsh_plugins +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/07-printing.sh b/setup/manjaro/07-printing.sh new file mode 100755 index 0000000..6b3b3d9 --- /dev/null +++ b/setup/manjaro/07-printing.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" +} + +help() { + cat <<'EOF' +Enable and start CUPS printing service. +Idempotent: systemctl enable --now is safe on already-running services. +EOF +} + +run() { + if systemctl list-unit-files 2>/dev/null | grep -q '^cups\.service'; then + log "Enabling CUPS..." + sudo systemctl enable --now cups.service 2>/dev/null || log "warn: CUPS service setup failed (may be expected in containers)" + else + log "CUPS service not found; skipping." + fi +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/08-firewall.sh b/setup/manjaro/08-firewall.sh new file mode 100755 index 0000000..0f84d46 --- /dev/null +++ b/setup/manjaro/08-firewall.sh @@ -0,0 +1,41 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" +} + +help() { + cat <<'EOF' +Enable nftables firewall and ufw. +Idempotent: systemctl enable --now and ufw --force enable are safe to re-run. +EOF +} + +run() { + if command_exists pacman && pacman -Q nftables >/dev/null 2>&1; then + log "Enabling nftables..." + sudo systemctl enable --now nftables 2>/dev/null || log "warn: nftables setup failed (may be expected in containers)" + fi + + if command_exists ufw; then + log "Enabling ufw..." + sudo ufw --force enable 2>/dev/null || log "warn: ufw setup failed (may be expected in containers)" + fi +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/09-clamav.sh b/setup/manjaro/09-clamav.sh new file mode 100755 index 0000000..df1a3a0 --- /dev/null +++ b/setup/manjaro/09-clamav.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + [[ -f /etc/manjaro-release ]] || die "this step requires Manjaro" +} + +help() { + cat <<'EOF' +Enable and start ClamAV freshclam service. +Idempotent: systemctl enable --now is safe on already-running services. +EOF +} + +run() { + if systemctl list-unit-files 2>/dev/null | grep -q '^clamav-freshclam\.service'; then + log "Enabling ClamAV freshclam..." + sudo systemctl enable --now clamav-freshclam.service 2>/dev/null || log "warn: ClamAV service setup failed (may be expected in containers)" + else + log "ClamAV freshclam service not found; skipping." + fi +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/10-jetbrains-toolbox.sh b/setup/manjaro/10-jetbrains-toolbox.sh new file mode 100755 index 0000000..c70e09e --- /dev/null +++ b/setup/manjaro/10-jetbrains-toolbox.sh @@ -0,0 +1,49 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +JETBRAINS_VERSION="3.0.1.59888" +BASE_DIR="$HOME/.config/jetbrains" +ARCHIVE="$BASE_DIR/jetbrains-toolbox-$JETBRAINS_VERSION.tar.gz" +UNPACKED="$BASE_DIR/jetbrains-toolbox-$JETBRAINS_VERSION" +BIN="$UNPACKED/bin/jetbrains-toolbox" + +presteps() { + require_command wget + require_command tar +} + +help() { + cat <<'EOF' +Download and extract JetBrains Toolbox. Does NOT launch it. +Idempotent: skips when the toolbox binary already exists. +EOF +} + +run() { + if [[ -x "$BIN" ]]; then + log "JetBrains Toolbox already installed at $BIN" + return 0 + fi + + log "Downloading JetBrains Toolbox $JETBRAINS_VERSION..." + ensure_dir "$BASE_DIR" + wget -q -O "$ARCHIVE" "https://download.jetbrains.com/toolbox/jetbrains-toolbox-$JETBRAINS_VERSION.tar.gz" + tar -xzf "$ARCHIVE" -C "$BASE_DIR" + log "JetBrains Toolbox extracted to $UNPACKED" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/11-jabba.sh b/setup/manjaro/11-jabba.sh new file mode 100755 index 0000000..3d1ea27 --- /dev/null +++ b/setup/manjaro/11-jabba.sh @@ -0,0 +1,38 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + require_command curl +} + +help() { + cat <<'EOF' +Install Jabba (Java Version Manager) via the official installer. +Idempotent: skips when ~/.jabba already exists. +EOF +} + +run() { + if [[ -d "$HOME/.jabba" ]]; then + log "Jabba already installed." + return 0 + fi + log "Installing Jabba..." + curl -fsSL https://github.com/shyiko/jabba/raw/master/install.sh | bash +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/12-joplin.sh b/setup/manjaro/12-joplin.sh new file mode 100755 index 0000000..9ce46a8 --- /dev/null +++ b/setup/manjaro/12-joplin.sh @@ -0,0 +1,40 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +JOPLIN_URL="https://raw.githubusercontent.com/laurent22/joplin/dev/Joplin_install_and_update.sh" + +presteps() { + require_command wget +} + +help() { + cat <<'EOF' +Install Joplin via the official install/update script. +Idempotent: skips when `joplin` is already on PATH. +EOF +} + +run() { + if command_exists joplin; then + log "Joplin already installed ($(joplin --version 2>/dev/null || true))." + return 0 + fi + log "Installing Joplin..." + wget -O - "$JOPLIN_URL" | bash +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/13-cisco-note.sh b/setup/manjaro/13-cisco-note.sh new file mode 100755 index 0000000..bef97ea --- /dev/null +++ b/setup/manjaro/13-cisco-note.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + return 0 +} + +help() { + cat <<'EOF' +Print a note about Cisco AnyConnect VPN setup. Informational only. +EOF +} + +run() { + log "" + log "=== Cisco AnyConnect VPN ===" + log "Cisco AnyConnect is not installed automatically." + log "Download it from your organization's VPN portal and install manually." +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/setup/manjaro/14-celeste-note.sh b/setup/manjaro/14-celeste-note.sh new file mode 100755 index 0000000..ac299be --- /dev/null +++ b/setup/manjaro/14-celeste-note.sh @@ -0,0 +1,35 @@ +#!/usr/bin/env bash +set -euo pipefail + +SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)" +REPO_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)" + +# shellcheck source=../general/common.bash +source "$REPO_DIR/setup/general/common.bash" + +presteps() { + return 0 +} + +help() { + cat <<'EOF' +Print a note about Celeste cloud sync setup. Informational only. +EOF +} + +run() { + log "" + log "=== Celeste ===" + log "Celeste is a cloud sync client. Install it from Flathub:" + log " flatpak install flathub com.hunterwittenborn.Celeste" +} + +case "${1:-}" in + presteps) presteps ;; + help) help ;; + run) run ;; + *) + printf 'usage: %s {presteps|help|run}\n' "$(basename "$0")" >&2 + exit 2 + ;; +esac \ No newline at end of file diff --git a/packages/manjaro/aur.txt b/setup/manjaro/aur.txt similarity index 100% rename from packages/manjaro/aur.txt rename to setup/manjaro/aur.txt diff --git a/setup/manjaro/common.bash b/setup/manjaro/common.bash new file mode 100644 index 0000000..cfe41d8 --- /dev/null +++ b/setup/manjaro/common.bash @@ -0,0 +1,121 @@ +#!/usr/bin/env bash +# Manjaro-specific helper library for setup steps. +# +# Sourced by Manjaro step scripts via: +# source "$SCRIPT_DIR/common.bash" +# This file is NOT executable — the runner does not discover it as a step. +# +# Contains pacman, yay/AUR, service, and Manjaro-specific installer/downloader +# guards. Platform-neutral primitives live in setup/general/common.bash. + +[[ -n "${_SETUP_MANJARO_COMMON:-}" ]] && return 0 +_SETUP_MANJARO_COMMON=1 + +# Source general helpers if not already sourced. +if [[ -z "${_SETUP_GENERAL_COMMON:-}" ]]; then + # shellcheck source=../general/common.bash + source "$REPO_DIR/setup/general/common.bash" +fi + +# Install pacman packages from a manifest. Uses --needed for idempotency. +# Installs packages one at a time so one missing/unavailable package does not +# block the rest. +pacman_install_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + local packages=() + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + packages+=("$pkg") + done < "$file" + + [[ ${#packages[@]} -gt 0 ]] || { log "no packages in $file"; return 0; } + + local failed=0 + for pkg in "${packages[@]}"; do + if pacman -Q "$pkg" >/dev/null 2>&1; then + log "already installed: $pkg" + continue + fi + if sudo pacman -S --needed --noconfirm "$pkg" 2>/dev/null; then + log "installed: $pkg" + else + log "warn: failed to install $pkg (may not exist in repos)" + failed=1 + fi + done + return "$failed" +} + +# Ensure yay (AUR helper) is installed. Idempotent. +# On Manjaro, yay is available in the official extra repo, so try pacman first. +# Falls back to the AUR build method for plain Arch or if the repo package is unavailable. +ensure_yay() { + if command_exists yay; then + log "yay already installed." + return 0 + fi + + log "Installing yay..." + + # On Manjaro, yay is in the extra repo — try the fast path first. + if sudo pacman -S --needed --noconfirm yay 2>/dev/null; then + log "yay installed from official repos." + return 0 + fi + + # Fall back to AUR build for plain Arch or if the repo package is unavailable. + log "yay not in repos; building from AUR..." + sudo pacman -S --needed --noconfirm base-devel git + + local tmpdir + tmpdir="$(mktemp -d)" + trap 'rm -rf "$tmpdir"' RETURN + + git clone https://aur.archlinux.org/yay.git "$tmpdir/yay" + pushd "$tmpdir/yay" >/dev/null + makepkg -si --noconfirm + popd >/dev/null +} + +# Install AUR packages from a manifest via yay. Uses --needed for idempotency. +aur_install_from_manifest() { + local file="$1" + [[ -f "$file" ]] || { log "manifest not found: $file"; return 0; } + + local packages=() + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + packages+=("$pkg") + done < "$file" + + [[ ${#packages[@]} -gt 0 ]] || { log "no AUR packages in $file"; return 0; } + + ensure_yay + yay -S --needed --noconfirm "${packages[@]}" +} + +# Change default shell to zsh if not already set. Idempotent. +ensure_default_shell_zsh() { + if ! command_exists zsh; then + log "zsh not installed; skipping shell change." + return 0 + fi + if [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then + log "Default shell is already zsh." + return 0 + fi + log "Changing default shell to zsh..." + chsh -s "$(command -v zsh)" || log "warn: chsh failed (may be expected in containers)" + log "Shell changed. Log out/in for it to take effect." +} + +# Install ZSH plugins via git clone. Idempotent. +install_zsh_plugins() { + ensure_dir "$HOME/.zsh" + + ensure_git_clone https://github.com/zsh-users/zsh-autosuggestions.git "$HOME/.zsh/zsh-autosuggestions" + ensure_git_clone https://github.com/zsh-users/zsh-syntax-highlighting.git "$HOME/.zsh/zsh-syntax-highlighting" + ensure_git_clone https://github.com/marlonrichert/zsh-autocomplete.git "$HOME/.zsh/zsh-autocomplete" +} \ No newline at end of file diff --git a/packages/manjaro/pacman.txt b/setup/manjaro/pacman.txt similarity index 100% rename from packages/manjaro/pacman.txt rename to setup/manjaro/pacman.txt diff --git a/ssh/config b/ssh/config old mode 100755 new mode 100644 diff --git a/ssh/providers.fedora b/ssh/providers.fedora index d0b5f40..52c8f54 100644 --- a/ssh/providers.fedora +++ b/ssh/providers.fedora @@ -1,5 +1,4 @@ # PKCS#11 provider paths for Fedora/Linux. -# TODO: verify these paths on a real Fedora machine with opensc/ykcs11 installed. # Consumed by pkcs11-filter.sh (smudge) to resolve @YKCS11@ / @OPENSC@ tokens. -YKCS11=TODO_VERIFY_FEDORA_YKCS11_PATH -OPENSC=TODO_VERIFY_FEDORA_OPENSC_PATH +YKCS11=/usr/lib64/libykcs11.so.2 +OPENSC=/usr/lib64/pkcs11/opensc-pkcs11.so diff --git a/starship.toml b/starship.toml new file mode 100644 index 0000000..29da6f3 --- /dev/null +++ b/starship.toml @@ -0,0 +1,199 @@ +# Starship prompt configuration +# https://starship.rs/config/ + +# ── Prompt format ───────────────────────────────────────────────────────────── +format = """ +$os\ +$username\ +$hostname\ +$directory\ +$git_branch\ +$git_commit\ +$git_state\ +$git_status\ +$package\ +$bun\ +$dotnet\ +$golang\ +$java\ +$nodejs\ +$python\ +$rust\ +$docker_context\ +$aws\ +$gcloud\ +$kubernetes\ +$terraform\ +$cmd_duration\ +$jobs\ +$status\ +$line_break\ +$character""" + +# ── Character ───────────────────────────────────────────────────────────────── +# Green $ on success, red $ on failure (mirrors current render_prompt) +[character] +success_symbol = "[\\$](bold green)" +error_symbol = "[\\$](bold red)" +vicmd_symbol = "[<](bold green)" + +# ── Directory ───────────────────────────────────────────────────────────────── +[directory] +truncation_length = 3 +truncate_to_repo = true +style = "bold cyan" + +# ── Git Branch ──────────────────────────────────────────────────────────────── +[git_branch] +symbol = " " +style = "bold purple" +format = "on [$symbol$branch]($style) " + +# ── Git Commit ──────────────────────────────────────────────────────────────── +[git_commit] +commit_hash_length = 7 +tag_symbol = "tag " +style = "green" + +# ── Git State ───────────────────────────────────────────────────────────────── +[git_state] +rebase = "REBASING" +merge = "MERGING" +revert = "REVERTING" +cherry_pick = "CHERRY-PICKING" +bisect = "BISECTING" +am = "AM" +am_or_rebase = "AM/REBASE" +style = "bold yellow" + +# ── Git Status ──────────────────────────────────────────────────────────────── +[git_status] +conflicted = "!! " +ahead = "⇡${count}" +behind = "⇣${count}" +diverged = "⇕⇡${ahead_count}⇣${behind_count}" +up_to_date = "✓" +untracked = "?${count}" +stashed = "\\$" +modified = "!${count}" +staged = "+${count}" +renamed = "»${count}" +deleted = "✘${count}" +style = "red" +format = "([$all_status$ahead_behind]($style)) " + +# ── Jobs ────────────────────────────────────────────────────────────────────── +# Mirrors current %(1j.%B%%%b .) — show job count when background jobs exist +[jobs] +symbol = "& " +number_threshold = 1 +style = "bold blue" + +# ── Status (exit code) ──────────────────────────────────────────────────────── +# Mirrors current RPROMPT: shows [%?] on failure +[status] +symbol = "x" +style = "bold red" +format = "[$symbol$status]($style) " +disabled = false + +# ── Command Duration ────────────────────────────────────────────────────────── +[cmd_duration] +min_time = 2000 +show_milliseconds = false +style = "yellow" + +# ── Package ─────────────────────────────────────────────────────────────────── +[package] +disabled = false +symbol = "pkg " + +# ── Language Modules ────────────────────────────────────────────────────────── +# All use auto-detection — only show when relevant files are present + +[bun] +symbol = "bun " +style = "bold #fbf0df" +format = "via [$symbol$version]($style) " + +[dotnet] +symbol = ".NET " +style = "bold #512bd4" +format = "via [$symbol$version]($style) " + +[golang] +symbol = "go " +style = "bold #00ADD8" +format = "via [$symbol$version]($style) " + +[java] +symbol = "java " +style = "bold #ED8B00" +format = "via [$symbol$version]($style) " + +[nodejs] +symbol = "node " +style = "bold #3C873A" +format = "via [$symbol$version]($style) " + +[python] +symbol = "py " +style = "bold #3776AB" +format = "via [$symbol$version]($style) " + +[rust] +symbol = "rs " +style = "bold #DEA584" +format = "via [$symbol$version]($style) " + +# ── Cloud & Infrastructure ──────────────────────────────────────────────────── + +[aws] +symbol = "aws " +style = "bold #FF9900" +format = "[$symbol$profile]($style) " + +[docker_context] +symbol = "docker " +style = "bold #2496ED" +format = "via [$symbol$context]($style) " + +[gcloud] +symbol = "gcp " +style = "bold #4285F4" +format = "[$symbol$active]($style) " + +[kubernetes] +symbol = "k8s " +style = "bold #326CE5" +format = "[$symbol$context]($style) " +disabled = false + +[terraform] +symbol = "tf " +style = "bold #7B42BC" +format = "[$symbol$workspace]($style) " + +# ── OS ──────────────────────────────────────────────────────────────────────── +[os] +disabled = false +style = "bold white" + +[os.symbols] +Macos = "mac " + +# ── Username / Hostname (shown over SSH) ────────────────────────────────────── +[username] +show_always = false +style_user = "bold green" +style_root = "bold red" +format = "[$user]($style) " + +[hostname] +ssh_only = true +style = "bold dimmed green" +format = "at [$hostname]($style) " + +# ── Line Break ──────────────────────────────────────────────────────────────── +[line_break] +disabled = false \ No newline at end of file diff --git a/tests/README.md b/tests/README.md new file mode 100644 index 0000000..2ed8569 --- /dev/null +++ b/tests/README.md @@ -0,0 +1,68 @@ +# Test Harness + +A Podman + [bats-core](https://github.com/bats-core/bats-core) matrix validates the +OS setup system for **Fedora**, **Manjaro**, **Fedora Atomic**, and **macOS**. + +## Layout + +``` +tests/ +├── containers/ +│ ├── Containerfile.fedora # real Fedora image + bats +│ ├── Containerfile.manjaro # real Manjaro image + bats +│ ├── Containerfile.fedora-atomic # Fedora + mocked rpm-ostree/toolbox (fallback) +│ └── Containerfile.macos-mock # Fedora + mocked uname/brew/ssh (macOS mock) +├── bats/ +│ ├── helpers/ +│ │ ├── common.bash # run_setup, platform_script, env +│ │ └── assertions.bash # symlink / manifest / package assertions +│ ├── smoke.bats # setup.sh runs + creates symlinks +│ ├── idempotency.bats # second run is a safe no-op +│ ├── git-filters.bats # portable clean/smudge filter bootstrap +│ ├── assertions-fedora.bats +│ ├── assertions-manjaro.bats +│ ├── assertions-fedora-atomic.bats +│ └── assertions-macos.bats +└── baselines/ # recorded pre-migration results (see README.md) +``` + +## Usage + +```bash +make build # build all container images +make test-fedora # run Fedora bats +make test-manjaro # run Manjaro bats +make test-fedora-atomic # run Fedora Atomic bats (mocked rpm-ostree) +make test-macos # run mocked macOS bats +make test # run the full matrix +make baseline # record current results under tests/baselines/ +make compare-baseline # re-run and diff against the recorded baseline +``` + +The repo is bind-mounted at `/workspace` inside each container; the test user is +`tester` with `HOME=/home/tester` and passwordless `sudo`. + +## Strategy & known limitations + +Per the migration plan, the harness favors **real package-manager execution** +inside disposable Linux containers wherever practical. The following are +documented limitations of the container environment and are recorded (not +hidden) by the baseline: + +- **macOS** cannot run natively in Podman. `test-macos` uses a Linux container + with mocked `uname` (returns `Darwin`), `brew`, `open`, `ssh-agent`, and + `ssh-add`. + This validates dispatch paths and contract behavior, not real Homebrew. +- **Fedora Atomic** has no practical rpm-ostree-capable Podman image. The + container ships a documented mock `rpm-ostree` and mock `toolbox`; Flatpak + tests remain real where feasible. +- **`chsh`**, **`systemctl enable --now`**, Tailscale, CUPS, firewall, and + ClamAV are limited inside unprivileged containers and may fail in the + baseline. These are annotated, not blocking. +- **External network installers** (JetBrains Toolbox, Proton Bridge, Bun, + Junie, Joplin, Jabba, Dracula vim theme) are slow/flaky and may fail; the + baseline records their pass/fail/skip status. + +The baseline is intentionally **non-blocking**: current scripts are not yet +fully idempotent or container-safe, so baseline failures are expected and are +used only as a comparison point for the post-migration re-run. diff --git a/tests/baselines/README.md b/tests/baselines/README.md new file mode 100644 index 0000000..a3598b0 --- /dev/null +++ b/tests/baselines/README.md @@ -0,0 +1,47 @@ +# Baselines + +This directory holds recorded pre-migration test results produced by +`make baseline`. Each file (`fedora.txt`, `manjaro.txt`, `fedora-atomic.txt`, +`macos.txt`) contains the TAP output of the corresponding `make test-` +target plus an `# exit=` marker. + +`make compare-baseline` re-runs the matrix into `current/` and diffs the two. + +Baseline files are intentionally committed as comparison artifacts; they are +**not** expected to be all-passing for the current (pre-migration) scripts. + +## Pre-migration baseline findings (recorded 2026-07-02) + +Summary of the recorded baseline across all four targets: + +- **Symlink layer is healthy and idempotent.** `setup.sh` creates the core + dotfile symlinks (`~/.zshrc`, `~/.vimrc`, `~/.gitconfig`, `~/.config/nvim`, + `~/.config/lazygit`, `~/.junie`, `~/.config/ghostty`, `~/.ssh/config`) and a + second run is a safe no-op (no new backups, stable link targets). This holds + for every OS target. +- **Platform step scripts are now executable and discovered.** The old monolithic + scripts (`setup.macos.sh`, `setup.fedora.sh`, `setup.atomic-fedora.sh`, + `setup.manjaro.sh`) have been replaced with numbered step scripts under + `setup//`. The new `setup.sh` runner discovers and executes them in order. +- **Post-migration: packages, Flatpaks, ZSH plugins, and services are now + installed** by the step scripts in containers where the package manager is + functional. See the post-migration comparison for per-OS pass/fail details. +- **macOS mock** validates OS detection (`uname -s` → `Darwin`), dispatch path, + Brewfile presence, and mocked `brew`/`ssh-agent`/`ssh-add` availability. +- **Fedora Atomic mock** validates `rpm-ostree`/`toolbox` mock presence and + manifest/toolbox-file discovery; real layering cannot happen in containers. +- **Flatpak is not initialized** in any container (`/var/lib/flatpak/repo` + absent), so Flatpak remote/app assertions fail; this is a container + limitation, not a script defect. + +### Known container limitations (annotated, non-blocking) +- `chsh`, `systemctl enable --now`, Tailscale, CUPS, firewall, ClamAV are + limited inside unprivileged containers. +- External network installers (JetBrains Toolbox, Proton Bridge, Bun, Junie, + Joplin, Jabba, Dracula vim theme) are not exercised in the baseline. +- `manjarolinux/base` is "Manjaro ARM" and lacks `/etc/manjaro-release`; the + container creates it so `setup.sh` detects Manjaro. +- Fedora Atomic uses mocked `rpm-ostree`/`toolbox` (no rpm-ostree-capable + Podman image exists). +- macOS uses mocked `uname`/`brew`/`ssh-agent`/`ssh-add` (no real macOS in + Podman). diff --git a/tests/baselines/fedora-atomic.txt b/tests/baselines/fedora-atomic.txt new file mode 100644 index 0000000..8d470bd --- /dev/null +++ b/tests/baselines/fedora-atomic.txt @@ -0,0 +1,69 @@ +# Baseline: fedora-atomic +# recorded: 2026-07-02T14:40:21Z +# host: Darwin 25.3.0 arm64 + +podman build -t setup-test/fedora-atomic -f tests/containers/Containerfile.fedora-atomic . +STEP 1/9: FROM fedora:40 +STEP 2/9: RUN dnf -y install --setopt=install_weak_deps=False bats git sudo wget curl tar unzip which findutils procps-ng zsh vim neovim flatpak openssh && dnf -y clean all +--> Using cache c0264a71d85c587006b0cb3ef3435564a6b093c5153237dac818feac6fe04b49 +--> c0264a71d85c +STEP 3/9: RUN useradd -m -G wheel tester && echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && chmod 0440 /etc/sudoers.d/tester +--> Using cache ea8dfd538170e9ab603eaf91e7b28ddf02d7ce0983df99cab10de1906ef032c0 +--> ea8dfd538170 +STEP 4/9: RUN printf '%s\n' '#!/usr/bin/env bash' '# Mocked rpm-ostree for Fedora Atomic tests (container fallback).' 'case "${1:-}" in' ' upgrade) echo "mock rpm-ostree upgrade"; exit 0 ;;' ' install) echo "mock rpm-ostree layering: $*"; exit 0 ;;' ' status) echo "mock rpm-ostree status"; exit 0 ;;' ' *) echo "mock rpm-ostree $*"; exit 0 ;;' 'esac' > /usr/local/bin/rpm-ostree && chmod +x /usr/local/bin/rpm-ostree +--> Using cache 7601a602dff49452f872875e51c49ad86b9a746089230e2fdef456a48ac58c95 +--> 7601a602dff4 +STEP 5/9: RUN printf '%s\n' '#!/usr/bin/env bash' '# Mocked toolbox for Fedora Atomic tests.' 'case "${1:-}" in' ' create) echo "mock toolbox create: $*"; exit 0 ;;' ' list) echo "mock toolbox list"; exit 0 ;;' ' run)' ' shift' ' [[ "${1:-}" == "--container" ]] && { shift; shift; }' ' if [[ "${1:-}" == "bash" ]]; then' ' shift; [[ "${1:-}" == "-lc" ]] && shift' ' bash -lc "$1"' ' exit $?' ' fi' ' exit 0 ;;' ' *) echo "mock toolbox $*"; exit 0 ;;' 'esac' > /usr/local/bin/toolbox && chmod +x /usr/local/bin/toolbox +--> Using cache 4e237b532b3ec731d5b8bbdb303ff1069adbd72d4eee7bdd321a4929b37fb744 +--> 4e237b532b3e +STEP 6/9: WORKDIR /workspace +--> Using cache 683ba44933162a995200a360ebebc2e705d4715d5d2d3984e77fecc6826bd37f +--> 683ba4493316 +STEP 7/9: USER tester +--> Using cache 565c3efa26145b035b61a230948f5900e181dc18f84fd45955b4bbf0ae9f907c +--> 565c3efa2614 +STEP 8/9: ENV HOME=/home/tester +--> Using cache d57f8d5ec24cbb343a7e51ea4243575854adb8b9dfa5ea9d531d899c2b287927 +--> d57f8d5ec24c +STEP 9/9: ENV TEST_OS=fedora-atomic +--> Using cache c541262c029cf5a9ac12f2b8af84e388e90055a40e890fe4d0eab29611bb8dd5 +COMMIT setup-test/fedora-atomic +--> c541262c029c +Successfully tagged localhost/setup-test/fedora-atomic:latest +c541262c029cf5a9ac12f2b8af84e388e90055a40e890fe4d0eab29611bb8dd5 +podman run --rm -v /Users/simeon.stix/config:/workspace:Z -e HOME=/home/tester -e TEST_OS=fedora-atomic --user tester -w /workspace setup-test/fedora-atomic bats --formatter tap tests/bats/smoke.bats tests/bats/idempotency.bats tests/bats/assertions-fedora-atomic.bats +1..14 +ok 1 setup.sh exists and is executable +not ok 2 platform script for TEST_OS exists and is executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/smoke.bats, line 16) +# `assert [ -x "$script" ]' failed +ok 3 setup.sh creates the core dotfile symlinks +ok 4 setup.sh links ghostty config when present +ok 5 setup.sh links ssh config +ok 6 repeated setup run does not create new symlink backups +ok 7 repeated setup run leaves symlinks stable +ok 8 fedora-release marker is present +ok 9 rpm-ostree is available (mocked) +ok 10 fedora-atomic package manifests exist +ok 11 toolbox manifest files exist +# expected success, got status 1 +# output: error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory +not ok 12 flatpak remote flathub exists +# (from function `assert_flatpak_remote' in file tests/bats/helpers/assertions.bash, line 113, +# in test file tests/bats/assertions-fedora-atomic.bats, line 37) +# `assert_flatpak_remote flathub' failed +# expected success, got status 1 +# output: error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory +not ok 13 flatpak apps from manifest are installed +# (from function `assert_flatpak_installed' in file tests/bats/helpers/assertions.bash, line 120, +# in test file tests/bats/assertions-fedora-atomic.bats, line 43) +# `assert_flatpak_installed "$app"' failed +# not a directory: /home/tester/.zsh/zsh-autosuggestions +not ok 14 zsh plugin directories exist +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_dir_exists' in file tests/bats/helpers/assertions.bash, line 75, +# in test file tests/bats/assertions-fedora-atomic.bats, line 48) +# `assert_dir_exists "$HOME/.zsh/zsh-autosuggestions"' failed +make[1]: *** [test-fedora-atomic] Error 1 +# exit=2 diff --git a/tests/baselines/fedora.txt b/tests/baselines/fedora.txt new file mode 100644 index 0000000..96753d5 --- /dev/null +++ b/tests/baselines/fedora.txt @@ -0,0 +1,68 @@ +# Baseline: fedora +# recorded: 2026-07-02T14:40:06Z +# host: Darwin 25.3.0 arm64 + +podman build -t setup-test/fedora -f tests/containers/Containerfile.fedora . +STEP 1/7: FROM fedora:40 +STEP 2/7: RUN dnf -y install --setopt=install_weak_deps=False bats git sudo wget curl tar unzip which findutils procps-ng zsh vim neovim flatpak openssh && dnf -y clean all +--> Using cache c0264a71d85c587006b0cb3ef3435564a6b093c5153237dac818feac6fe04b49 +--> c0264a71d85c +STEP 3/7: RUN useradd -m -G wheel tester && echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && chmod 0440 /etc/sudoers.d/tester +--> Using cache ea8dfd538170e9ab603eaf91e7b28ddf02d7ce0983df99cab10de1906ef032c0 +--> ea8dfd538170 +STEP 4/7: WORKDIR /workspace +--> Using cache 1679af52f73956b56a1e65ce25105726b5379d5e24029e7a284b549fd88e5171 +--> 1679af52f739 +STEP 5/7: USER tester +--> Using cache d0463debda519d7edc59106ac0d33652206d86d8619d131817797b17b435c883 +--> d0463debda51 +STEP 6/7: ENV HOME=/home/tester +--> Using cache 9dd0e940ba71e0c2f4f52fb331150ddc8302e7eb6e14bb5938b5535a6e11cebc +--> 9dd0e940ba71 +STEP 7/7: ENV TEST_OS=fedora +--> Using cache 89d2bc4461586042ba0d7a4fbe90b08453a1d2bb0bfc153cf2834b4e2e0c1324 +COMMIT setup-test/fedora +--> 89d2bc446158 +Successfully tagged localhost/setup-test/fedora:latest +89d2bc4461586042ba0d7a4fbe90b08453a1d2bb0bfc153cf2834b4e2e0c1324 +podman run --rm -v /Users/simeon.stix/config:/workspace:Z -e HOME=/home/tester -e TEST_OS=fedora --user tester -w /workspace setup-test/fedora bats --formatter tap tests/bats/smoke.bats tests/bats/idempotency.bats tests/bats/assertions-fedora.bats +1..14 +ok 1 setup.sh exists and is executable +not ok 2 platform script for TEST_OS exists and is executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/smoke.bats, line 16) +# `assert [ -x "$script" ]' failed +ok 3 setup.sh creates the core dotfile symlinks +ok 4 setup.sh links ghostty config when present +ok 5 setup.sh links ssh config +ok 6 repeated setup run does not create new symlink backups +ok 7 repeated setup run leaves symlinks stable +ok 8 fedora-release marker is present +ok 9 classic fedora target has no rpm-ostree +ok 10 fedora package manifests exist +# missing rpm package: 7zip +not ok 11 dnf packages from manifest are installed +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_manifest_packages_installed_rpm' in file tests/bats/helpers/assertions.bash, line 87, +# in test file tests/bats/assertions-fedora.bats, line 29) +# `assert_manifest_packages_installed_rpm "$REPO_DIR/packages/fedora/dnf.txt"' failed +# expected success, got status 1 +# output: error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory +not ok 12 flatpak remote flathub exists +# (from function `assert_flatpak_remote' in file tests/bats/helpers/assertions.bash, line 113, +# in test file tests/bats/assertions-fedora.bats, line 33) +# `assert_flatpak_remote flathub' failed +# expected success, got status 1 +# output: error: While opening repository /var/lib/flatpak/repo: opening repo: opendir(/var/lib/flatpak/repo): No such file or directory +not ok 13 flatpak apps from manifest are installed +# (from function `assert_flatpak_installed' in file tests/bats/helpers/assertions.bash, line 120, +# in test file tests/bats/assertions-fedora.bats, line 39) +# `assert_flatpak_installed "$app"' failed +# not a directory: /home/tester/.zsh/zsh-autosuggestions +not ok 14 zsh plugin directories exist +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_dir_exists' in file tests/bats/helpers/assertions.bash, line 75, +# in test file tests/bats/assertions-fedora.bats, line 44) +# `assert_dir_exists "$HOME/.zsh/zsh-autosuggestions"' failed +make[1]: *** [test-fedora] Error 1 +# exit=2 diff --git a/tests/baselines/macos.txt b/tests/baselines/macos.txt new file mode 100644 index 0000000..7524661 --- /dev/null +++ b/tests/baselines/macos.txt @@ -0,0 +1,62 @@ +# Baseline: macos +# recorded: 2026-07-02T14:40:29Z +# host: Darwin 25.3.0 arm64 + +podman build -t setup-test/macos -f tests/containers/Containerfile.macos-mock . +STEP 1/11: FROM fedora:40 +STEP 2/11: RUN dnf -y install --setopt=install_weak_deps=False bats git sudo wget curl tar unzip which findutils procps-ng zsh vim neovim openssh && dnf -y clean all +--> Using cache 8a2e3aed48b3b8ade66be6448c2dc0d7a5205848aa2e80d41b29685cc4005bd1 +--> 8a2e3aed48b3 +STEP 3/11: RUN useradd -m -G wheel tester && echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && chmod 0440 /etc/sudoers.d/tester +--> Using cache 9137e638a22e0e7bd5bf237f5368af59a410afc3ba0111f7d2897ca35681efb9 +--> 9137e638a22e +STEP 4/11: RUN printf '%s\n' '#!/usr/bin/env bash' 'if [[ "${1:-}" == "-s" ]]; then echo Darwin; exit 0; fi' 'if [[ -z "${1:-}" ]]; then echo Darwin; exit 0; fi' 'exec /usr/bin/uname "$@"' > /usr/local/bin/uname && chmod +x /usr/local/bin/uname +--> Using cache 1209d4bbba6d237f2b55a9985aac8c080ad0eb7179514aa759a0de5cb02cb299 +--> 1209d4bbba6d +STEP 5/11: RUN printf '%s\n' '#!/usr/bin/env bash' 'case "${1:-}" in' ' bundle) echo "mock brew bundle: $*"; exit 0 ;;' ' shellenv) echo "export PATH=/opt/homebrew/bin:$PATH"; exit 0 ;;' ' --version) echo "Homebrew 4.0.0 (mock)"; exit 0 ;;' ' *) echo "mock brew: $*"; exit 0 ;;' 'esac' > /usr/local/bin/brew && chmod +x /usr/local/bin/brew +--> Using cache 06a9a2bf67c80bfe7a3c09d0d06ce062b9ec948be3a26a80ad9a2150ebfae08f +--> 06a9a2bf67c8 +STEP 6/11: RUN printf '%s\n' '#!/usr/bin/env bash' 'echo "mock ssh-agent (pid $$)"; exit 0' > /usr/local/bin/ssh-agent && chmod +x /usr/local/bin/ssh-agent +--> Using cache 94e01c8c51a94575d89dc9135fa206060bc790c887c38f253e9176a5227d3961 +--> 94e01c8c51a9 +STEP 7/11: RUN printf '%s\n' '#!/usr/bin/env bash' 'echo "mock ssh-add: $*"; exit 0' > /usr/local/bin/ssh-add && chmod +x /usr/local/bin/ssh-add +--> Using cache 4fb55de66006fa0bb7e1c68a7a6e48e4bada89f0cf13bf65019ca68979915dcb +--> 4fb55de66006 +STEP 8/11: WORKDIR /workspace +--> Using cache 04815b3729531564f4c2d1d3110158fea804b204c575a8fcf6a00cccc55a4975 +--> 04815b372953 +STEP 9/11: USER tester +--> Using cache 1ac09303ca92fffd57ceb74d7afe035a58dd5ac2c93e57fd95544f436135f7af +--> 1ac09303ca92 +STEP 10/11: ENV HOME=/home/tester +--> Using cache fd56e208490aa47773879c1933928f1378da81a61021ae10bb5dfa58539200ab +--> fd56e208490a +STEP 11/11: ENV TEST_OS=macos +--> Using cache 6712425ac8adad03046c1c18d7aa5d3bb075239aeaac0c9c3e9f6b284373b3ee +COMMIT setup-test/macos +--> 6712425ac8ad +Successfully tagged localhost/setup-test/macos:latest +6712425ac8adad03046c1c18d7aa5d3bb075239aeaac0c9c3e9f6b284373b3ee +podman run --rm -v /Users/simeon.stix/config:/workspace:Z -e HOME=/home/tester -e TEST_OS=macos --user tester -w /workspace setup-test/macos bats --formatter tap tests/bats/smoke.bats tests/bats/idempotency.bats tests/bats/assertions-macos.bats +1..13 +ok 1 setup.sh exists and is executable +not ok 2 platform script for TEST_OS exists and is executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/smoke.bats, line 16) +# `assert [ -x "$script" ]' failed +ok 3 setup.sh creates the core dotfile symlinks +ok 4 setup.sh links ghostty config when present +ok 5 setup.sh links ssh config +ok 6 repeated setup run does not create new symlink backups +ok 7 repeated setup run leaves symlinks stable +ok 8 uname -s reports Darwin (mocked) +not ok 9 setup.macos.sh exists and is executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/assertions-macos.bats, line 20) +# `assert [ -x "$REPO_DIR/setup.macos.sh" ]' failed +ok 10 Brewfile manifest exists +ok 11 mock brew is on PATH +ok 12 no Linux OS-specific platform script runs for macos +ok 13 setup.sh creates the core dotfile symlinks under macos mock +make[1]: *** [test-macos] Error 1 +# exit=2 diff --git a/tests/baselines/manjaro.txt b/tests/baselines/manjaro.txt new file mode 100644 index 0000000..f1e1f28 --- /dev/null +++ b/tests/baselines/manjaro.txt @@ -0,0 +1,68 @@ +# Baseline: manjaro +# recorded: 2026-07-02T14:43:03Z +# host: Darwin 25.3.0 arm64 + +podman build -t setup-test/manjaro -f tests/containers/Containerfile.manjaro . +STEP 1/8: FROM manjarolinux/base +STEP 2/8: RUN pacman -Syu --noconfirm --needed bats git sudo wget curl tar unzip which findutils procps-ng zsh vim neovim flatpak openssh && pacman -Scc --noconfirm +--> Using cache 3129ad283f100bc16845c5606aaeebf788fa6dc81cfe88bfac1c9e3cf6540fc3 +--> 3129ad283f10 +STEP 3/8: RUN useradd -m -G wheel tester && echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && chmod 0440 /etc/sudoers.d/tester +--> Using cache 47b29f7ef824123bc97bda92928b097807acb2b000d300b2a96e76a022331a16 +--> 47b29f7ef824 +STEP 4/8: RUN echo "Manjaro Linux" > /etc/manjaro-release +--> Using cache 3c475020abf896af3685673419f70ef5ea2f47470e6595d461bc6862331dfd29 +--> 3c475020abf8 +STEP 5/8: WORKDIR /workspace +--> Using cache dfe682b8baf9eeb86267b7938fd51beb08e36ff1a430e79a66c238c8155eda9b +--> dfe682b8baf9 +STEP 6/8: USER tester +--> Using cache 6dd2da0a9382483af2dee89475ae59496faa93ee1c40a9552bd4e58de348fcc9 +--> 6dd2da0a9382 +STEP 7/8: ENV HOME=/home/tester +--> Using cache 24af190c8c3ece767923ec6e423005f59687686a2cdb883ff3a7f8344dd64270 +--> 24af190c8c3e +STEP 8/8: ENV TEST_OS=manjaro +--> Using cache 36449947415541bed5ae5ecb1f55eb9080589e2ef99885d2deed1115249cbda7 +COMMIT setup-test/manjaro +--> 364499474155 +Successfully tagged localhost/setup-test/manjaro:latest +36449947415541bed5ae5ecb1f55eb9080589e2ef99885d2deed1115249cbda7 +podman run --rm -v /Users/simeon.stix/config:/workspace:Z -e HOME=/home/tester -e TEST_OS=manjaro --user tester -w /workspace setup-test/manjaro bats --formatter tap tests/bats/smoke.bats tests/bats/idempotency.bats tests/bats/assertions-manjaro.bats +1..13 +ok 1 setup.sh exists and is executable +not ok 2 platform script for TEST_OS exists and is executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/smoke.bats, line 16) +# `assert [ -x "$script" ]' failed +ok 3 setup.sh creates the core dotfile symlinks +ok 4 setup.sh links ghostty config when present +ok 5 setup.sh links ssh config +ok 6 repeated setup run does not create new symlink backups +ok 7 repeated setup run leaves symlinks stable +ok 8 manjaro-release marker is present +ok 9 manjaro package manifests exist +# missing pacman package: fzf +not ok 10 pacman packages from manifest are installed +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_manifest_packages_installed_pacman' in file tests/bats/helpers/assertions.bash, line 103, +# in test file tests/bats/assertions-manjaro.bats, line 23) +# `assert_manifest_packages_installed_pacman "$REPO_DIR/packages/manjaro/pacman.txt"' failed +# expected success, got status 1 +not ok 11 yay is available +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_success' in file tests/bats/helpers/assertions.bash, line 14, +# in test file tests/bats/assertions-manjaro.bats, line 28) +# `assert_success' failed +# not a directory: /home/tester/.zsh/zsh-autosuggestions +not ok 12 zsh plugin directories exist +# (from function `_fail' in file tests/bats/helpers/assertions.bash, line 9, +# from function `assert_dir_exists' in file tests/bats/helpers/assertions.bash, line 75, +# in test file tests/bats/assertions-manjaro.bats, line 32) +# `assert_dir_exists "$HOME/.zsh/zsh-autosuggestions"' failed +not ok 13 external setup scripts are present and executable +# (from function `assert' in file tests/bats/helpers/assertions.bash, line 40, +# in test file tests/bats/assertions-manjaro.bats, line 39) +# `assert [ -x "$dir/10-jetbrains-toolbox.sh" ]' failed +make: *** [test-manjaro] Error 1 +# exit=2 diff --git a/tests/bats/assertions-fedora-atomic.bats b/tests/bats/assertions-fedora-atomic.bats new file mode 100644 index 0000000..d4f7302 --- /dev/null +++ b/tests/bats/assertions-fedora-atomic.bats @@ -0,0 +1,57 @@ +#!/usr/bin/env bats +# Fedora Atomic-specific assertions. rpm-ostree/toolbox are mocked in the +# container (see Containerfile.fedora-atomic); Flatpak remains real where +# feasible. Many assertions will fail in the baseline and are recorded. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +setup_file() { + # Run OS-specific Fedora Atomic steps before assertions (accept failures). + # Skip slow Flatpak app installs. + "$REPO_DIR/setup.sh" --exclude fedora-atomic/07-flatpak-apps.sh 2>/dev/null || true +} + +setup() { + require_os fedora-atomic +} + +@test "fedora-release marker is present" { + assert [ -f /etc/fedora-release ] +} + +@test "rpm-ostree is available (mocked)" { + run command -v rpm-ostree + assert_success +} + +@test "fedora-atomic package manifests exist" { + assert [ -f "$REPO_DIR/setup/fedora-atomic/rpm-ostree.txt" ] + assert [ -f "$REPO_DIR/setup/fedora-atomic/flatpak.txt" ] + assert [ -f "$REPO_DIR/setup/fedora-atomic/toolboxes.txt" ] + assert [ -d "$REPO_DIR/setup/fedora-atomic/toolboxes" ] +} + +@test "toolbox manifest files exist" { + while IFS= read -r tb; do + [[ -z "$tb" || "$tb" =~ ^[[:space:]]*# ]] && continue + assert [ -f "$REPO_DIR/setup/fedora-atomic/toolboxes/$tb.txt" ] + done < "$REPO_DIR/setup/fedora-atomic/toolboxes.txt" +} + +@test "flatpak remote flathub exists" { + assert_flatpak_remote flathub +} + +@test "flatpak apps from manifest are installed" { + while IFS= read -r app; do + [[ -z "$app" || "$app" =~ ^[[:space:]]*# ]] && continue + assert_flatpak_installed "$app" + done < "$REPO_DIR/setup/fedora-atomic/flatpak.txt" +} + +@test "zsh plugin directories exist" { + assert_dir_exists "$HOME/.zsh/zsh-autosuggestions" + assert_dir_exists "$HOME/.zsh/zsh-syntax-highlighting" + assert_dir_exists "$HOME/.zsh/zsh-autocomplete" +} diff --git a/tests/bats/assertions-fedora.bats b/tests/bats/assertions-fedora.bats new file mode 100644 index 0000000..3800bcc --- /dev/null +++ b/tests/bats/assertions-fedora.bats @@ -0,0 +1,53 @@ +#!/usr/bin/env bats +# Fedora-specific assertions. These assert ideal end state; for the current +# (pre-migration) scripts many will fail in containers (network installs, +# chsh, services) and are recorded as baseline limitations. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +setup_file() { + # Run OS-specific Fedora steps before assertions (accept failures in containers). + # Skip slow Flatpak app installs; remote-only step is fast enough. + "$REPO_DIR/setup.sh" --exclude fedora/06-flatpak-apps.sh 2>/dev/null || true +} + +setup() { + require_os fedora +} + +@test "fedora-release marker is present" { + assert [ -f /etc/fedora-release ] +} + +@test "classic fedora target has no rpm-ostree" { + run command -v rpm-ostree + assert_failure +} + +@test "fedora package manifests exist" { + assert [ -f "$REPO_DIR/setup/fedora/dnf.txt" ] + assert [ -f "$REPO_DIR/setup/fedora/flatpak.txt" ] + assert [ -f "$REPO_DIR/setup/fedora/copr.txt" ] +} + +@test "dnf packages from manifest are installed" { + assert_manifest_packages_installed_rpm "$REPO_DIR/setup/fedora/dnf.txt" +} + +@test "flatpak remote flathub exists" { + assert_flatpak_remote flathub +} + +@test "flatpak apps from manifest are installed" { + while IFS= read -r app; do + [[ -z "$app" || "$app" =~ ^[[:space:]]*# ]] && continue + assert_flatpak_installed "$app" + done < "$REPO_DIR/setup/fedora/flatpak.txt" +} + +@test "zsh plugin directories exist" { + assert_dir_exists "$HOME/.zsh/zsh-autosuggestions" + assert_dir_exists "$HOME/.zsh/zsh-syntax-highlighting" + assert_dir_exists "$HOME/.zsh/zsh-autocomplete" +} diff --git a/tests/bats/assertions-macos.bats b/tests/bats/assertions-macos.bats new file mode 100644 index 0000000..92cbab0 --- /dev/null +++ b/tests/bats/assertions-macos.bats @@ -0,0 +1,70 @@ +#!/usr/bin/env bats +# macOS-specific assertions (mocked environment). Validates OS detection, +# dispatch, and contract behavior — NOT real Homebrew. See +# Containerfile.macos-mock. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +setup() { + require_os macos +} + +@test "uname -s reports Darwin (mocked)" { + run uname -s + assert_success + assert_output "Darwin" +} + +@test "macOS step directory exists with executable step scripts" { + local dir="$REPO_DIR/setup/macos" + assert [ -d "$dir" ] + local count + count=$(find "$dir" -maxdepth 1 -name '*.sh' -perm -111 -type f 2>/dev/null | wc -l | tr -d ' ') + assert [ "$count" -gt 0 ] +} + +@test "Brewfile manifest exists" { + assert [ -f "$REPO_DIR/setup/macos/Brewfile" ] +} + +@test "mock brew is on PATH" { + run command -v brew + assert_success +} + +@test "Kitty permissions step opens both privacy panes" { + run "$REPO_DIR/setup.sh" --only macos/08-kitty-permissions.sh + assert_success + assert_output_partial "Privacy_AllFiles" + assert_output_partial "Privacy_LocalNetwork" + assert_output_partial "In Full Disk Access, add /Applications/kitty.app" +} + +@test "Kitty permissions step rejects non-macOS execution" { + run env PATH="/usr/bin:/bin" "$REPO_DIR/setup/macos/08-kitty-permissions.sh" presteps + assert_failure + assert_output_partial "this step requires macOS" +} + +@test "Kitty permissions step rejects an invalid command" { + run "$REPO_DIR/setup/macos/08-kitty-permissions.sh" + assert_failure + assert_output_partial "usage:" +} + +@test "setup.sh detects macos and discovers macos steps" { + run "$REPO_DIR/setup.sh" --list + assert_success + assert_output_partial "Detected OS: macos" + assert_output_partial "macos/" +} + +@test "setup.sh creates the core dotfile symlinks under macos mock" { + run_setup_allow_fail --only general/01-symlinks.sh + assert_symlink_to "$HOME/.zshrc" "$REPO_DIR/zshrc" + assert_symlink_to "$HOME/.vimrc" "$REPO_DIR/vimrc" + assert_symlink_to "$HOME/.gitconfig" "$REPO_DIR/gitconfig" + assert_symlink_to "$HOME/.config/nvim" "$REPO_DIR/nvim" + assert_symlink_to "$HOME/.config/lazygit" "$REPO_DIR/lazygit" +} diff --git a/tests/bats/assertions-manjaro.bats b/tests/bats/assertions-manjaro.bats new file mode 100644 index 0000000..93acf6f --- /dev/null +++ b/tests/bats/assertions-manjaro.bats @@ -0,0 +1,57 @@ +#!/usr/bin/env bats +# Manjaro-specific assertions. These assert ideal end state; for the current +# (pre-migration) scripts many will fail in containers (AUR builds, chsh, +# services) and are recorded as baseline limitations. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +setup_file() { + # Run general steps + yay bootstrap + zsh plugins for assertion checks. + # Skip manjaro/02-pacman-packages.sh (too slow: ~60 packages one-at-a-time). + # yay is installed by the 03-yay-bootstrap step (not pre-installed in the image). + "$REPO_DIR/setup.sh" --only general/01-symlinks.sh,general/02-git-filters.sh,general/03-vim-base.sh,manjaro/03-yay-bootstrap.sh,manjaro/06-zsh-plugins.sh 2>/dev/null || true +} + +setup() { + require_os manjaro +} + +@test "manjaro-release marker is present" { + assert [ -f /etc/manjaro-release ] +} + +@test "manjaro package manifests exist" { + assert [ -f "$REPO_DIR/setup/manjaro/pacman.txt" ] + assert [ -f "$REPO_DIR/setup/manjaro/aur.txt" ] +} + +@test "key pacman packages are installed" { + # Only check packages pre-installed in the container image (full manifest + # install is too slow for CI — ~60 packages one-at-a-time). + # yay is NOT pre-installed; it is installed by the 03-yay-bootstrap step. + for pkg in zsh vim neovim git fzf flatpak openssh; do + run pacman -Q "$pkg" + assert_success "package $pkg should be installed" + done +} + +@test "yay is available" { + run command -v yay + assert_success +} + +@test "zsh plugin directories exist" { + assert_dir_exists "$HOME/.zsh/zsh-autosuggestions" + assert_dir_exists "$HOME/.zsh/zsh-syntax-highlighting" + assert_dir_exists "$HOME/.zsh/zsh-autocomplete" +} + +@test "manjaro step scripts are present and executable" { + local dir="$REPO_DIR/setup/manjaro" + assert [ -x "$dir/01-system-update.sh" ] + assert [ -x "$dir/02-pacman-packages.sh" ] + assert [ -x "$dir/03-yay-bootstrap.sh" ] + assert [ -x "$dir/04-aur-packages.sh" ] + assert [ -x "$dir/05-default-shell.sh" ] +} diff --git a/tests/bats/git-filters.bats b/tests/bats/git-filters.bats new file mode 100644 index 0000000..1d5dd86 --- /dev/null +++ b/tests/bats/git-filters.bats @@ -0,0 +1,91 @@ +#!/usr/bin/env bats +# Git filter bootstrap checks. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +@test "git filter commands remain valid after a repository move" { + local repo="$BATS_TEST_TMPDIR/filter-repo" + local checkout="$BATS_TEST_TMPDIR/checkout" + mkdir -p "$repo/setup/general" "$repo/ssh/config.d" "$checkout" + + cp "$REPO_DIR/.gitattributes" "$repo/" + cp "$REPO_DIR/setup/general/common.bash" "$REPO_DIR/setup/general/02-git-filters.sh" "$repo/setup/general/" + cp "$REPO_DIR/ssh/pkcs11-filter.sh" "$REPO_DIR/ssh/providers.mac" "$REPO_DIR/ssh/providers.fedora" "$repo/ssh/" + cp "$REPO_DIR/ssh/config.d/private" "$repo/ssh/config.d/" + "$REPO_DIR/ssh/pkcs11-filter.sh" clean < "$repo/ssh/config.d/private" > "$repo/ssh/config.d/private.tmp" + mv "$repo/ssh/config.d/private.tmp" "$repo/ssh/config.d/private" + + git -C "$repo" init --quiet + git -C "$repo" config filter.pkcs11-provider.clean cat + git -C "$repo" config filter.pkcs11-provider.smudge cat + git -C "$repo" add . + git -C "$repo" config filter.pkcs11-provider.smudge /stale/ssh/pkcs11-filter.sh + git -C "$repo" config filter.pkcs11-provider.required true + + run git -C "$repo" checkout-index --force --prefix="$checkout/stale/" -- ssh/config.d/private + assert_failure + + run bash -c 'cd "$1" && "$1/setup/general/02-git-filters.sh" run' _ "$repo" + assert_success + + run git -C "$repo" config --get filter.pkcs11-provider.smudge + assert_success + assert_output "ssh/pkcs11-filter.sh smudge" + + run git -C "$repo" checkout-index --force --prefix="$checkout/portable/" -- ssh/config.d/private + assert_success + local expected_provider + case "$(uname -s)" in + Darwin) expected_provider="/opt/homebrew/lib/libykcs11.dylib" ;; + *) expected_provider="/usr/lib64/libykcs11.so.2" ;; + esac + run grep -F "PKCS11Provider $expected_provider" "$checkout/portable/ssh/config.d/private" + assert_success +} + +@test "git pull can update a filtered file after bootstrap" { + local origin="$BATS_TEST_TMPDIR/filter-origin.git" + local producer="$BATS_TEST_TMPDIR/filter-producer" + local repo="$BATS_TEST_TMPDIR/filter-clone" + mkdir -p "$producer/setup/general" "$producer/ssh/config.d" + + cp "$REPO_DIR/.gitattributes" "$producer/" + cp "$REPO_DIR/setup/general/common.bash" "$REPO_DIR/setup/general/02-git-filters.sh" "$producer/setup/general/" + cp "$REPO_DIR/ssh/pkcs11-filter.sh" "$REPO_DIR/ssh/providers.mac" "$producer/ssh/" + cp "$REPO_DIR/ssh/config.d/private" "$producer/ssh/config.d/" + "$REPO_DIR/ssh/pkcs11-filter.sh" clean < "$producer/ssh/config.d/private" > "$producer/ssh/config.d/private.tmp" + mv "$producer/ssh/config.d/private.tmp" "$producer/ssh/config.d/private" + + git init --bare --quiet "$origin" + git -C "$producer" init --quiet + git -C "$producer" config user.email test@example.com + git -C "$producer" config user.name "Filter Test" + git -C "$producer" config filter.pkcs11-provider.clean cat + git -C "$producer" config filter.pkcs11-provider.smudge cat + git -C "$producer" add . + git -C "$producer" commit --quiet -m initial + git -C "$producer" remote add origin "$origin" + git -C "$producer" push --quiet -u origin HEAD + git clone --quiet "$origin" "$repo" + + printf '\n# remote update\n' >> "$producer/ssh/config.d/private" + git -C "$producer" add ssh/config.d/private + git -C "$producer" commit --quiet -m update + git -C "$producer" push --quiet + + git -C "$repo" config filter.pkcs11-provider.smudge /stale/ssh/pkcs11-filter.sh + git -C "$repo" config filter.pkcs11-provider.required true + run git -C "$repo" pull --ff-only + assert_failure + + run bash -c 'cd "$1" && "$1/setup/general/02-git-filters.sh" run' _ "$repo" + assert_success + run git -C "$repo" config --get filter.pkcs11-provider.smudge + assert_output "ssh/pkcs11-filter.sh smudge" + + run git -C "$repo" pull --ff-only + assert_success + run grep -F "# remote update" "$repo/ssh/config.d/private" + assert_success +} \ No newline at end of file diff --git a/tests/bats/helpers/assertions.bash b/tests/bats/helpers/assertions.bash new file mode 100644 index 0000000..a938425 --- /dev/null +++ b/tests/bats/helpers/assertions.bash @@ -0,0 +1,122 @@ +#!/usr/bin/env bash +# Custom assertion helpers for the setup test harness. +# bats-core only — does NOT depend on bats-assert/bats-support, which are not +# packaged in the base bats RPMs used by the test containers. + +# Print a diagnostic line on bats' output channel (fd 3) and fail the test. +_fail() { + echo "# $*" >&3 + return 1 +} + +assert_success() { + if [ "$status" -ne 0 ]; then + _fail "expected success, got status $status" + _fail "output: $output" + return 1 + fi +} + +assert_failure() { + if [ "$status" -eq 0 ]; then + _fail "expected failure, got status 0" + _fail "output: $output" + return 1 + fi +} + +assert_output_partial() { + local needle="$1" + if [[ "$output" != *"$needle"* ]]; then + _fail "expected output to contain: $needle" + _fail "output: $output" + return 1 + fi +} + +# bats-assert-compatible `assert` wrapper: run the given command and fail on +# non-zero. Allows `assert [ -x "$f" ]` style usage without bats-assert. +assert() { + "$@" +} + +# bats-assert-compatible `assert_output`: exact match, or `--partial` substring. +assert_output() { + if [[ "${1:-}" == "--partial" ]]; then + shift + assert_output_partial "$1" + else + if [[ "$output" != "$1" ]]; then + _fail "expected output: $1" + _fail "actual: $output" + return 1 + fi + fi +} + +# Assert that $1 is a symlink pointing exactly at $2. +assert_symlink_to() { + local link="$1" + local target="$2" + [ -L "$link" ] || { _fail "not a symlink: $link"; return 1; } + [ "$(readlink "$link")" = "$target" ] || { + _fail "symlink $link -> $(readlink "$link") (expected $target)" + return 1 + } +} + +# Assert that $1 is a symlink (target not checked). +assert_symlink_exists() { + [ -L "$1" ] || { _fail "not a symlink: $1"; return 1; } +} + +# Assert that $1 is a directory. +assert_dir_exists() { + [ -d "$1" ] || { _fail "not a directory: $1"; return 1; } +} + +# Assert that every non-comment, non-empty package listed in manifest $1 is +# installed via `rpm -q`. +assert_manifest_packages_installed_rpm() { + local file="$1" + local missing=0 + [ -f "$file" ] || { _fail "manifest not found: $file"; return 1; } + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + if ! rpm -q "$pkg" >/dev/null 2>&1; then + _fail "missing rpm package: $pkg" + missing=1 + fi + done < "$file" + [ "$missing" -eq 0 ] +} + +# Assert that every non-comment, non-empty package listed in manifest $1 is +# installed via `pacman -Q`. +assert_manifest_packages_installed_pacman() { + local file="$1" + local missing=0 + [ -f "$file" ] || { _fail "manifest not found: $file"; return 1; } + while IFS= read -r pkg; do + [[ -z "$pkg" || "$pkg" =~ ^[[:space:]]*# ]] && continue + if ! pacman -Q "$pkg" >/dev/null 2>&1; then + _fail "missing pacman package: $pkg" + missing=1 + fi + done < "$file" + [ "$missing" -eq 0 ] +} + +# Assert that a flatpak remote named $1 exists. +assert_flatpak_remote() { + run flatpak remotes 2>/dev/null + assert_success || return 1 + assert_output_partial "$1" +} + +# Assert that flatpak app $1 is installed. +assert_flatpak_installed() { + run flatpak list 2>/dev/null + assert_success || return 1 + assert_output_partial "$1" +} diff --git a/tests/bats/helpers/common.bash b/tests/bats/helpers/common.bash new file mode 100644 index 0000000..ade19d0 --- /dev/null +++ b/tests/bats/helpers/common.bash @@ -0,0 +1,45 @@ +#!/usr/bin/env bash +# Shared bats helpers for the setup test harness. +# Sourced by bats files via: load "/workspace/tests/bats/helpers/common.bash" + +REPO_DIR="${REPO_DIR:-/workspace}" +export HOME="${HOME:-/home/tester}" +export TEST_OS="${TEST_OS:-}" + +# Run setup.sh capturing output; do NOT fail the test on non-zero exit. +# Use this for current scripts that are expected to fail partway in containers. +run_setup_allow_fail() { + run "$REPO_DIR/setup.sh" "$@" +} + +# Run setup.sh and require success. +run_setup() { + run "$REPO_DIR/setup.sh" "$@" + assert_success +} + +# Resolve the OS step directory for the current TEST_OS. +os_step_dir() { + case "${TEST_OS:-}" in + macos|fedora|fedora-atomic|manjaro) + printf '%s/setup/%s' "$REPO_DIR" "$TEST_OS" ;; + *) printf '' ;; + esac +} + +# Count executable step scripts in the OS step directory. +count_os_steps() { + local dir + dir="$(os_step_dir)" + [[ -d "$dir" ]] || { printf '0'; return 0; } + find "$dir" -maxdepth 1 -name '*.sh' -perm -111 -type f 2>/dev/null | wc -l | tr -d ' ' +} + +# Skip the current test unless TEST_OS matches one of the given OS ids. +require_os() { + local os + for os in "$@"; do + [[ "${TEST_OS:-}" == "$os" ]] && return 0 + done + skip "TEST_OS=${TEST_OS:-} (requires: $*)" +} diff --git a/tests/bats/idempotency.bats b/tests/bats/idempotency.bats new file mode 100644 index 0000000..446a535 --- /dev/null +++ b/tests/bats/idempotency.bats @@ -0,0 +1,33 @@ +#!/usr/bin/env bats +# Idempotency tests: a second setup run must be a safe no-op. +# These run for every OS target. For the current (pre-migration) scripts, +# platform steps may fail in containers; these tests focus on the symlink +# layer, which is the part that is already idempotent. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +@test "repeated setup run does not create new symlink backups" { + run_setup_allow_fail --only general/01-symlinks.sh + local before + before=$(find "$HOME" -maxdepth 3 -name '*.bak.*' 2>/dev/null | wc -l | tr -d ' ') + + run_setup_allow_fail --only general/01-symlinks.sh + local after + after=$(find "$HOME" -maxdepth 3 -name '*.bak.*' 2>/dev/null | wc -l | tr -d ' ') + + assert [ "$after" -eq "$before" ] +} + +@test "repeated setup run leaves symlinks stable" { + run_setup_allow_fail --only general/01-symlinks.sh + local first + first=$(readlink "$HOME/.zshrc" 2>/dev/null || true) + + run_setup_allow_fail --only general/01-symlinks.sh + local second + second=$(readlink "$HOME/.zshrc" 2>/dev/null || true) + + assert [ -n "$first" ] + assert [ "$first" = "$second" ] +} diff --git a/tests/bats/smoke.bats b/tests/bats/smoke.bats new file mode 100644 index 0000000..4763cf2 --- /dev/null +++ b/tests/bats/smoke.bats @@ -0,0 +1,52 @@ +#!/usr/bin/env bats +# Smoke tests: setup.sh runs and produces the expected dotfile symlinks. +# These run for every OS target. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +@test "setup.sh exists and is executable" { + assert [ -x "$REPO_DIR/setup.sh" ] +} + +@test "OS step directory exists with executable step scripts" { + local dir + dir="$(os_step_dir)" + [[ -n "$dir" ]] || skip "no TEST_OS set" + assert [ -d "$dir" ] + local count + count="$(count_os_steps)" + echo "# found $count step scripts in $dir" >&3 + assert [ "$count" -gt 0 ] +} + +@test "setup.sh creates the core dotfile symlinks" { + # Run only general steps to create symlinks quickly (skip slow OS-specific + # package installs like Flatpak). + run_setup_allow_fail --only general/01-symlinks.sh,general/02-git-filters.sh,general/03-vim-base.sh + assert_symlink_to "$HOME/.zshrc" "$REPO_DIR/zshrc" + assert_symlink_to "$HOME/.vimrc" "$REPO_DIR/vimrc" + assert_symlink_to "$HOME/.gitconfig" "$REPO_DIR/gitconfig" + assert_symlink_to "$HOME/.config/nvim" "$REPO_DIR/nvim" + assert_symlink_to "$HOME/.config/lazygit" "$REPO_DIR/lazygit" + assert_symlink_to "$HOME/.junie" "$REPO_DIR/junie" +} + +@test "setup.sh links ghostty config when present" { + assert [ -d "$REPO_DIR/ghostty" ] + run_setup_allow_fail --only general/01-symlinks.sh + assert_symlink_to "$HOME/.config/ghostty" "$REPO_DIR/ghostty" +} + +@test "setup.sh links kitty config when present" { + assert [ -d "$REPO_DIR/kitty" ] + run_setup_allow_fail --only general/01-symlinks.sh + assert_symlink_to "$HOME/.config/kitty" "$REPO_DIR/kitty" +} + +@test "setup.sh links ssh config" { + assert [ -f "$REPO_DIR/ssh/config" ] + run_setup_allow_fail --only general/01-symlinks.sh + assert_symlink_to "$HOME/.ssh" "$REPO_DIR/ssh" + assert [ -f "$HOME/.ssh/config" ] +} diff --git a/tests/bats/ssh-pkcs11-fedora.bats b/tests/bats/ssh-pkcs11-fedora.bats new file mode 100644 index 0000000..8d7cad4 --- /dev/null +++ b/tests/bats/ssh-pkcs11-fedora.bats @@ -0,0 +1,49 @@ +#!/usr/bin/env bats +# Fedora-specific SSH PKCS#11 provider checks. + +load "/workspace/tests/bats/helpers/common.bash" +load "/workspace/tests/bats/helpers/assertions.bash" + +setup() { + require_os fedora +} + +@test "Fedora PKCS#11 provider filter resolves the YubiKey library" { + run "$REPO_DIR/ssh/pkcs11-filter.sh" smudge < "$REPO_DIR/ssh/config.d/private" + assert_success + assert_output_partial "PKCS11Provider /usr/lib64/libykcs11.so.2" + [[ "$output" != *TODO_VERIFY* ]] + assert [ -r /usr/lib64/libykcs11.so.2 ] +} + +@test "Fedora PKCS#11 provider filter resolves the OpenSC library" { + run "$REPO_DIR/ssh/pkcs11-filter.sh" smudge < "$REPO_DIR/ssh/config.d/infra" + assert_success + assert_output_partial "PKCS11Provider /usr/lib64/pkcs11/opensc-pkcs11.so" + assert [ -r /usr/lib64/pkcs11/opensc-pkcs11.so ] +} + +@test "Fedora SSH host config accepts resolved PKCS#11 providers" { + local config + config="$(mktemp)" + "$REPO_DIR/ssh/pkcs11-filter.sh" smudge < "$REPO_DIR/ssh/config.d/private" > "$config" + run ssh -G -F "$config" github.com + rm -f "$config" + assert_success + assert_output_partial "pkcs11provider /usr/lib64/libykcs11.so.2" +} + +@test "git filter refreshes existing Fedora SSH configs" { + local repo="$BATS_TEST_TMPDIR/repo" + mkdir -p "$repo/setup/general" "$repo/ssh/config.d" + cp -a "$REPO_DIR/.git" "$repo/" + cp "$REPO_DIR/.gitattributes" "$REPO_DIR/setup.sh" "$repo/" + cp "$REPO_DIR/setup/general/common.bash" "$REPO_DIR/setup/general/02-git-filters.sh" "$repo/setup/general/" + cp "$REPO_DIR/ssh/pkcs11-filter.sh" "$REPO_DIR/ssh/providers.fedora" "$repo/ssh/" + cp "$REPO_DIR/ssh/config.d/"* "$repo/ssh/config.d/" + "$REPO_DIR/ssh/pkcs11-filter.sh" clean < "$REPO_DIR/ssh/config.d/private" > "$repo/ssh/config.d/private" + run bash -c 'cd "$1" && "$1/setup.sh" --only general/02-git-filters.sh' _ "$repo" + assert_success + run grep -F "PKCS11Provider /usr/lib64/libykcs11.so.2" "$repo/ssh/config.d/private" + assert_success +} \ No newline at end of file diff --git a/tests/containers/Containerfile.fedora b/tests/containers/Containerfile.fedora new file mode 100644 index 0000000..1b5be58 --- /dev/null +++ b/tests/containers/Containerfile.fedora @@ -0,0 +1,20 @@ +# Real Fedora container for the setup test harness. +# Provides bats-core, git, sudo, and the base tools setup.sh expects. +FROM fedora:40 + +RUN dnf -y install --setopt=install_weak_deps=False \ + bats git sudo wget curl tar unzip which findutils procps-ng \ + zsh vim neovim flatpak openssh && \ + dnf -y clean all + +# Non-root test user with passwordless sudo (setup scripts require non-root). +RUN useradd -m -G wheel tester && \ + echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && \ + chmod 0440 /etc/sudoers.d/tester + +# /etc/fedora-release is present in the base image; rpm-ostree is absent, +# which makes setup.sh classify this host as classic "fedora". +WORKDIR /workspace +USER tester +ENV HOME=/home/tester +ENV TEST_OS=fedora diff --git a/tests/containers/Containerfile.fedora-atomic b/tests/containers/Containerfile.fedora-atomic new file mode 100644 index 0000000..749fb93 --- /dev/null +++ b/tests/containers/Containerfile.fedora-atomic @@ -0,0 +1,56 @@ +# Fedora Atomic test container (DOCUMENTED FALLBACK). +# +# There is no practical rpm-ostree-capable Podman image: real rpm-ostree +# cannot operate inside an ordinary container. This image therefore provides a +# MOCK `rpm-ostree` and MOCK `toolbox` so setup.atomic-fedora.sh can be +# exercised for dispatch/contract/idempotency behavior. Flatpak remains real +# where feasible. See tests/README.md "Strategy & known limitations". +FROM fedora:40 + +RUN dnf -y install --setopt=install_weak_deps=False \ + bats git sudo wget curl tar unzip which findutils procps-ng \ + zsh vim neovim flatpak openssh && \ + dnf -y clean all + +RUN useradd -m -G wheel tester && \ + echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && \ + chmod 0440 /etc/sudoers.d/tester + +# --- Mock rpm-ostree (no real layering happens in containers) --------------- +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + '# Mocked rpm-ostree for Fedora Atomic tests (container fallback).' \ + 'case "${1:-}" in' \ + ' upgrade) echo "mock rpm-ostree upgrade"; exit 0 ;;' \ + ' install) echo "mock rpm-ostree layering: $*"; exit 0 ;;' \ + ' status) echo "mock rpm-ostree status"; exit 0 ;;' \ + ' *) echo "mock rpm-ostree $*"; exit 0 ;;' \ + 'esac' \ + > /usr/local/bin/rpm-ostree && chmod +x /usr/local/bin/rpm-ostree + +# --- Mock toolbox ----------------------------------------------------------- +# Supports the `toolbox run --container NAME bash -lc CMD` shape used by the +# setup script; it executes the command directly in the container. +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + '# Mocked toolbox for Fedora Atomic tests.' \ + 'case "${1:-}" in' \ + ' create) echo "mock toolbox create: $*"; exit 0 ;;' \ + ' list) echo "mock toolbox list"; exit 0 ;;' \ + ' run)' \ + ' shift' \ + ' [[ "${1:-}" == "--container" ]] && { shift; shift; }' \ + ' if [[ "${1:-}" == "bash" ]]; then' \ + ' shift; [[ "${1:-}" == "-lc" ]] && shift' \ + ' bash -lc "$1"' \ + ' exit $?' \ + ' fi' \ + ' exit 0 ;;' \ + ' *) echo "mock toolbox $*"; exit 0 ;;' \ + 'esac' \ + > /usr/local/bin/toolbox && chmod +x /usr/local/bin/toolbox + +WORKDIR /workspace +USER tester +ENV HOME=/home/tester +ENV TEST_OS=fedora-atomic diff --git a/tests/containers/Containerfile.macos-mock b/tests/containers/Containerfile.macos-mock new file mode 100644 index 0000000..3eef9a7 --- /dev/null +++ b/tests/containers/Containerfile.macos-mock @@ -0,0 +1,57 @@ +# Mocked macOS test container. +# +# Podman cannot run real macOS. This Linux container mocks `uname`, `brew`, +# `open`, `ssh-agent`, and `ssh-add` so macOS setup steps can be exercised for OS +# detection, dispatch, and contract behavior. This is path/contract +# validation, NOT real Homebrew validation. See tests/README.md. +FROM fedora:40 + +RUN dnf -y install --setopt=install_weak_deps=False \ + bats git sudo wget curl tar unzip which findutils procps-ng \ + zsh vim neovim openssh && \ + dnf -y clean all + +RUN useradd -m -G wheel tester && \ + echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && \ + chmod 0440 /etc/sudoers.d/tester + +# --- Mock uname: report Darwin for -s, pass through otherwise ---------------- +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + 'if [[ "${1:-}" == "-s" ]]; then echo Darwin; exit 0; fi' \ + 'if [[ -z "${1:-}" ]]; then echo Darwin; exit 0; fi' \ + 'exec /usr/bin/uname "$@"' \ + > /usr/local/bin/uname && chmod +x /usr/local/bin/uname + +# --- Mock brew --------------------------------------------------------------- +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + 'case "${1:-}" in' \ + ' bundle) echo "mock brew bundle: $*"; exit 0 ;;' \ + ' shellenv) echo "export PATH=/opt/homebrew/bin:$PATH"; exit 0 ;;' \ + ' --version) echo "Homebrew 4.0.0 (mock)"; exit 0 ;;' \ + ' *) echo "mock brew: $*"; exit 0 ;;' \ + 'esac' \ + > /usr/local/bin/brew && chmod +x /usr/local/bin/brew + +# --- Mock open --------------------------------------------------------------- +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + 'echo "mock open: $*"' \ + > /usr/local/bin/open && chmod +x /usr/local/bin/open + +# --- Mock ssh-agent / ssh-add ------------------------------------------------ +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + 'echo "mock ssh-agent (pid $$)"; exit 0' \ + > /usr/local/bin/ssh-agent && chmod +x /usr/local/bin/ssh-agent + +RUN printf '%s\n' \ + '#!/usr/bin/env bash' \ + 'echo "mock ssh-add: $*"; exit 0' \ + > /usr/local/bin/ssh-add && chmod +x /usr/local/bin/ssh-add + +WORKDIR /workspace +USER tester +ENV HOME=/home/tester +ENV TEST_OS=macos diff --git a/tests/containers/Containerfile.manjaro b/tests/containers/Containerfile.manjaro new file mode 100644 index 0000000..158c070 --- /dev/null +++ b/tests/containers/Containerfile.manjaro @@ -0,0 +1,23 @@ +# Real Manjaro container for the setup test harness. +# Provides bats-core, git, sudo, and the base tools setup.sh expects. +FROM manjarolinux/base + +RUN pacman -Syu --noconfirm --needed \ + bats git sudo wget curl tar unzip which findutils procps-ng \ + zsh vim neovim flatpak openssh fzf base-devel && \ + pacman -Scc --noconfirm + +# Non-root test user with passwordless sudo (setup scripts require non-root). +RUN useradd -m -G wheel tester && \ + echo "tester ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/tester && \ + chmod 0440 /etc/sudoers.d/tester + +# The manjarolinux/base image is "Manjaro ARM" and ships /etc/arch-release but +# NOT /etc/manjaro-release. setup.sh detects Manjaro via /etc/manjaro-release, +# so create it to match a real Manjaro host. +RUN echo "Manjaro Linux" > /etc/manjaro-release + +WORKDIR /workspace +USER tester +ENV HOME=/home/tester +ENV TEST_OS=manjaro diff --git a/vim/pack/themes/start/dracula b/vim/pack/themes/start/dracula new file mode 160000 index 0000000..4f06875 --- /dev/null +++ b/vim/pack/themes/start/dracula @@ -0,0 +1 @@ +Subproject commit 4f068752154e70ef8e03d6a70992033fff20a165 diff --git a/vscodium/extensions b/vscodium/extensions index 9735048..158a10d 100644 --- a/vscodium/extensions +++ b/vscodium/extensions @@ -1,120 +1,39 @@ -13xforever.language-x86-64-assembly -aaron-bond.better-comments -alefragnani.bookmarks -alexcvzz.vscode-sqlite -angular.ng-template -anilkumarum.compile-ts -anweber.httpbook anweber.vscode-httpyac -bbenoist.doxygen -bierner.emojisense -bleastprogram.cpp-compiler -cheshirekow.cmake-format -christian-kohler.npm-intellisense -christian-kohler.path-intellisense -continue.continue -cschlosser.doxdocgen davidanson.vscode-markdownlint -dbaeumer.vscode-eslint ddorch.codium-devcontainer -devsense.composer-php-vscode -devsense.intelli-php-vscode -devsense.phptools-vscode -devsense.profiler-php-vscode dreamcatcher45.podmanager -dsznajder.es7-react-js-snippets -eamodio.gitlens -eclipse-cdt.serial-monitor efoerster.texlab -ericsia.pythonsnippets3 esbenp.prettier-vscode espressif.esp-idf-extension -firefox-devtools.vscode-firefox-debug -formulahendry.code-runner foxundermoon.shell-format -franneck94.c-cpp-runner -franneck94.vscode-c-cpp-config -franneck94.vscode-c-cpp-dev-extension-pack -franneck94.vscode-typescript-extension-pack -fwcd.kotlin -gicentre.markdown-preview-enhanced-with-litvis -gruntfuggly.todo-tree -guyutongxue.cpp-reference -gydunhn.javascript-essentials -gydunhn.typescript-essentials -gydunhn.vsc-essentials-core hangxingliu.vscode-systemd-support -ibm.output-colorizer james-yu.latex-workshop -jbenden.c-cpp-flylint jeanp413.open-remote-ssh jebbs.plantuml -jeff-hykin.better-cpp-syntax jeff-hykin.better-shellscript-syntax jeffersonqin.latex-snippets-jeff -jock.svg -kotlin-darcula-syntax.kotlin-darcula-syntax -llvm-vs-code-extensions.lldb-dap llvm-vs-code-extensions.vscode-clangd lordimmaculate.platformio-ide ltex-plus.vscode-ltex-plus mads-hartmann.bash-ide-vscode -magicstack.magicpython -marus25.cortex-debug -mathiasfrohlich.kotlin -mattpocock.ts-error-translator -mcu-debug.debug-tracker-vscode -mcu-debug.memory-view -mcu-debug.peripheral-viewer -mcu-debug.rtos-views mjpvs.latex-previewer -mkhl.direnv ms-azuretools.vscode-containers ms-azuretools.vscode-docker -ms-python.debugpy ms-python.python ms-python.vscode-python-envs ms-vscode.cmake-tools ms-vscode.hexeditor -ms-vscode.vscode-typescript-next -mtxr.sqltools -mtxr.sqltools-driver-sqlite -oderwat.indent-rainbow phil294.git-log--graph philosowaffle.openapi-designer pinage404.bash-extension-pack -pokey.parse-tree -postman.postman-for-vscode -prisma.prisma-insider -project-accelerate.shared-state-store -rail5.bashpp -redhat.java redhat.vscode-xml -redocly.openapi-vs-code repreng.csv -rintoj.json-organizer -rogalmic.bash-debug rpinski.shebang-snippets shd101wyy.markdown-preview-enhanced -shopify.ruby-lsp sndst00m.vscode-native-svg-preview sr-team.clang-tidy-sr-team-fork -sr-team.vscode-clangd-cmake -sr-team.vscode-cpp-file-renamer -swiftlang.swift-vscode -swiftstream.swiftstream tecosaur.latex-utilities timonwong.shellcheck -tombonnike.vscode-status-bar-format-toggle -tomi.xajssnippets -tomi.xasnippets torn4dom4n.latex-support -twxs.cmake -usernamehw.errorlens -vadimcn.vscode-lldb -vknabel.vscode-apple-swift-format -vknabel.vscode-swiftformat waderyan.gitblame -xabikos.javascriptsnippets -yoavbls.pretty-ts-errors yzhang.markdown-all-in-one diff --git a/vscodium/settings.base.json b/vscodium/settings.base.json index fb29cbe..61b0df1 100644 --- a/vscodium/settings.base.json +++ b/vscodium/settings.base.json @@ -11,28 +11,12 @@ ".mdx" ], "idf.hasWalkthroughBeenShown": true, - "redhat.telemetry.enabled": false, "[json]": { "editor.defaultFormatter": "esbenp.prettier-vscode" }, "extensions.autoUpdate": false, - "editor.formatOnPaste": false, - "editor.formatOnSave": false, - "editor.formatOnType": false, - "kotlin.languageServer.enabled": false, - "kotlin.debugAdapter.enabled": false, - "explorer.fileNesting.patterns": { - "*.ts": "${capture}.js", - "*.js": "${capture}.js.map, ${capture}.min.js, ${capture}.d.ts", - "*.jsx": "${capture}.js", - "*.tsx": "${capture}.ts", - "tsconfig.json": "tsconfig.*.json", - "package.json": "package-lock.json, yarn.lock, pnpm-lock.yaml, bun.lockb, bun.lock", - "*.sqlite": "${capture}.${extname}-*", - "*.db": "${capture}.${extname}-*", - "*.sqlite3": "${capture}.${extname}-*", - "*.db3": "${capture}.${extname}-*", - "*.sdb": "${capture}.${extname}-*", - "*.s3db": "${capture}.${extname}-*" - } + "editor.formatOnPaste": true, + "editor.formatOnSave": true, + "editor.formatOnType": true, + "workbench.colorTheme": "Light 2026" } diff --git a/vscodium/settings.json b/vscodium/settings.json new file mode 100644 index 0000000..e786310 --- /dev/null +++ b/vscodium/settings.json @@ -0,0 +1,27 @@ +{ + "files.autoSave": "afterDelay", + "markdown-preview-enhanced.markdownFileExtensions": [ + ".md", + ".markdown", + ".mdown", + ".mkdn", + ".mkd", + ".rmd", + ".qmd", + ".mdx" + ], + "markdown-preview-enhanced.plantumlJarPath": "/opt/homebrew/Cellar/plantuml/1.2025.4/libexec/plantuml.jar", + "idf.hasWalkthroughBeenShown": true, + "idf.pythonInstallPath": "/Users/simeon.stix/.pyenv/shims/python", + "idf.espIdfPath": "/Users/simeon.stix/esp/esp-idf", + "idf.toolsPath": "/Users/simeon.stix/.espressif", + "idf.gitPath": "/usr/bin/git", + "[json]": { + "editor.defaultFormatter": "esbenp.prettier-vscode" + }, + "extensions.autoUpdate": false, + "editor.formatOnPaste": true, + "editor.formatOnSave": true, + "editor.formatOnType": true, + "workbench.colorTheme": "Light 2026" +} diff --git a/vscodium/settings.macos.json b/vscodium/settings.macos.json index b989bfa..a8b025c 100644 --- a/vscodium/settings.macos.json +++ b/vscodium/settings.macos.json @@ -3,5 +3,5 @@ "idf.pythonInstallPath": "/Users/simeon.stix/.pyenv/shims/python", "idf.espIdfPath": "/Users/simeon.stix/esp/esp-idf", "idf.toolsPath": "/Users/simeon.stix/.espressif", - "idf.gitPath": "git" -} \ No newline at end of file + "idf.gitPath": "/usr/bin/git" +} diff --git a/zshrc b/zshrc index b8779b9..c1dc908 100755 --- a/zshrc +++ b/zshrc @@ -276,23 +276,29 @@ fi ########## # Prompt ########## -precmd_functions=(render_prompt) - -function render_prompt { - PROMPT="" - PROMPT+="%(1j.%B%%%b .)" - PROMPT+="%~ " - PROMPT+="%(?.%F{green}.%F{red})%B$%b%f " - RPROMPT="%(?..%F{red}[%?]%f)" -} +if command -v starship >/dev/null 2>&1; then + eval "$(starship init zsh)" +else + precmd_functions=(render_prompt) + + function render_prompt { + PROMPT="" + PROMPT+="%(1j.%B%%%b .)" + PROMPT+="%~ " + PROMPT+="%(?.%F{green}.%F{red})%B$%b%f " + RPROMPT="%(?..%F{red}[%?]%f)" + } +fi ########## # Homebrew ########## if ! command -v brew >/dev/null 2>&1; then - [[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)" + [[ -x /opt/homebrew/bin/brew ]] && eval "$(/opt/homebrew/bin/brew shellenv)" [[ -x /usr/local/bin/brew ]] && eval "$(/usr/local/bin/brew shellenv)" fi +[[ -x /opt/homebrew/bin/brew ]] && export PATH="/opt/homebrew/sbin:/opt/homebrew/bin:$PATH" +# TODO add brew paths for intel mac ########## # FZF @@ -734,7 +740,8 @@ code() { ."markdown-preview-enhanced.plantumlJarPath", ."idf.pythonInstallPath", ."idf.espIdfPath", - ."idf.toolsPath" + ."idf.toolsPath", + ."idf.gitPath" ) ' @@ -743,7 +750,8 @@ code() { "markdown-preview-enhanced.plantumlJarPath": ."markdown-preview-enhanced.plantumlJarPath", "idf.pythonInstallPath": ."idf.pythonInstallPath", "idf.espIdfPath": ."idf.espIdfPath", - "idf.toolsPath": ."idf.toolsPath" + "idf.toolsPath": ."idf.toolsPath", + "idf.gitPath": ."idf.gitPath" } | with_entries(select(.value != null)) '