README
¶
jungi
An opinionated coding harness for large language models that provides workflows for planning, executing, and reviewing. Includes support for tools, skills, subagents, reusable prompts, and hooks.
Installation
Requires Go 1.25+.
go install git.dick.codes/jungi/cmd/jungi@latest
The binary is installed to $GOBIN, falling back to $GOPATH/bin (default ~/go/bin). Make sure that directory is on your $PATH:
export PATH="$PATH:$(go env GOPATH)/bin"
Authentication
On first launch, run /credentials from the command palette to enter your API keys for LLM providers and other integrated services. Note: jungi does not read provider API keys from environment variables; keys must be set via /credentials.
Documentation
Detailed documentation lives in the docs/ folder:
- Usage — modes, keybindings, status bar, and git worktree isolation.
- Commands — the slash command reference, including
/plan,/execute, and/review. - Tools — the tools the agent can call, sandboxing, and tool approval.
- Skills — the skill system and how to write your own skills.
- Agents — what subagents are, how agents are defined, and the built-in agents.
- Configuration —
settings.toml, models, reasoning, worktrees, prompts, and user guidance. - Hooks — the lifecycle hook system for running scripts on jungi events.
Contributing
Outside contributions to this project are not being solicited at this time. Contact the maintainer via email if you wish to report a bug or request a feature. Patches are accepted via git-send-mail.
Maintainer: Dick Davis
Building
make build
Running tests
make test
Linting
make vet
make fmt
Releasing
make release VERSION=vX.Y.Z
License
AGPLv3 or later. See LICENSE.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
jungi
command
jungi is a terminal chat application for conversing with Claude models.
|
jungi is a terminal chat application for conversing with Claude models. |
|
internal
|
|
|
agents
Package agents provides jungi's built-in agent definitions as an embedded filesystem.
|
Package agents provides jungi's built-in agent definitions as an embedded filesystem. |
|
agents/reviewer
Package reviewer provides definitions for per-perspective code review agents.
|
Package reviewer provides definitions for per-perspective code review agents. |
|
core/agentreg
Package agentreg provides subagent infrastructure for jungi.
|
Package agentreg provides subagent infrastructure for jungi. |
|
core/approval
Package approval defines the request/response types used when the model invokes tools that require user approval.
|
Package approval defines the request/response types used when the model invokes tools that require user approval. |
|
core/auth
Package auth manages credentials stored on disk.
|
Package auth manages credentials stored on disk. |
|
core/autoapprove
Package autoapprove provides an AI-powered evaluator for tool approval decisions.
|
Package autoapprove provides an AI-powered evaluator for tool approval decisions. |
|
core/compact
Package compact implements the /compact slash command logic and idle autocompaction summarisation.
|
Package compact implements the /compact slash command logic and idle autocompaction summarisation. |
|
core/config
Package config resolves well-known filesystem paths for jungi data.
|
Package config resolves well-known filesystem paths for jungi data. |
|
core/control
Package control implements the client side of the "jungi control" remote messenger service integration.
|
Package control implements the client side of the "jungi control" remote messenger service integration. |
|
core/export
Package export writes a session's message history to disk as JSON Lines so users can inspect or archive a conversation outside the TUI.
|
Package export writes a session's message history to disk as JSON Lines so users can inspect or archive a conversation outside the TUI. |
|
core/git
Package git provides low-level git helpers used by the plan executor and worktree manager.
|
Package git provides low-level git helpers used by the plan executor and worktree manager. |
|
core/hooksreg
Package hooksreg implements a lifecycle hook system for jungi.
|
Package hooksreg implements a lifecycle hook system for jungi. |
|
core/logger
Package logger provides structured, append-only event logging for jungi.
|
Package logger provides structured, append-only event logging for jungi. |
|
core/lsp
Package lsp drives Language Server Protocol clients for a jungi session.
|
Package lsp drives Language Server Protocol clients for a jungi session. |
|
core/mdreg
Package mdreg provides the shared foundation for jungi's markdown-plus- frontmatter "content registries": agentreg, promptreg, and skillreg.
|
Package mdreg provides the shared foundation for jungi's markdown-plus- frontmatter "content registries": agentreg, promptreg, and skillreg. |
|
core/modelcache
Package modelcache persists resolved model.Config values to disk so OpenRouter model configs survive a restart without requiring a fresh catalog fetch.
|
Package modelcache persists resolved model.Config values to disk so OpenRouter model configs survive a restart without requiring a fresh catalog fetch. |
|
core/modelresolve
Package modelresolve fetches fresh model.Config values for every OpenRouter model named in settings at startup, so a stale or absent cache entry never lets a session run against pricing/context data that no longer matches what OpenRouter reports.
|
Package modelresolve fetches fresh model.Config values for every OpenRouter model named in settings at startup, so a stale or absent cache entry never lets a session run against pricing/context data that no longer matches what OpenRouter reports. |
|
core/orchestrator
Package orchestrator provides a reusable plan → fan-out → assemble pipeline for coordinating multiple subagents.
|
Package orchestrator provides a reusable plan → fan-out → assemble pipeline for coordinating multiple subagents. |
|
core/planengine
Package planengine implements the storage, tools, and embedded skills that power the /plan and /execute slash commands.
|
Package planengine implements the storage, tools, and embedded skills that power the /plan and /execute slash commands. |
|
core/promptreg
Package promptreg loads user-defined prompts from disk and exposes them to sessions as a first-class registry.
|
Package promptreg loads user-defined prompts from disk and exposes them to sessions as a first-class registry. |
|
core/reorder
Package reorder implements a single, collision-safe algorithm for moving a row to a new 1-based position among its ord-ordered siblings.
|
Package reorder implements a single, collision-safe algorithm for moving a row to a new 1-based position among its ord-ordered siblings. |
|
core/review
Package review provides the orchestration factory for the /review command.
|
Package review provides the orchestration factory for the /review command. |
|
core/sandbox
Package sandbox provides platform-aware process sandboxing.
|
Package sandbox provides platform-aware process sandboxing. |
|
core/scaffold
Package scaffold creates a new user's jungi configuration directory structure on first startup, so every later path resolution (settings, logs, skills, hooks) finds its directory already present.
|
Package scaffold creates a new user's jungi configuration directory structure on first startup, so every later path resolution (settings, logs, skills, hooks) finds its directory already present. |
|
core/session
Package session ties together the message history, usage totals, and identity for one continuous conversation with the model.
|
Package session ties together the message history, usage totals, and identity for one continuous conversation with the model. |
|
core/sessiontitle
Package sessiontitle generates short, descriptive kebab-case title slugs for chat sessions using a single-turn structured JSON LLM call over conversation history.
|
Package sessiontitle generates short, descriptive kebab-case title slugs for chat sessions using a single-turn structured JSON LLM call over conversation history. |
|
core/settings
Package settings loads and validates user configuration for jungi.
|
Package settings loads and validates user configuration for jungi. |
|
core/skillreg
Package skillreg loads filesystem-based skills from disk and exposes them to the model via a jungi built-in tool.
|
Package skillreg loads filesystem-based skills from disk and exposes them to the model via a jungi built-in tool. |
|
core/statestore
Package statestore owns the shared SQLite database that jungi keeps under <repo>/.jungi/state/state.db.
|
Package statestore owns the shared SQLite database that jungi keeps under <repo>/.jungi/state/state.db. |
|
core/systemprompt
Package systemprompt builds the system prompt sent with every API request.
|
Package systemprompt builds the system prompt sent with every API request. |
|
core/tasklist
Package tasklist implements a small, self-contained store for labelled, ordered collections of tasks.
|
Package tasklist implements a small, self-contained store for labelled, ordered collections of tasks. |
|
core/toolexec
Package toolexec orchestrates the agentic tool-use loop between the provider API client and local tool execution.
|
Package toolexec orchestrates the agentic tool-use loop between the provider API client and local tool execution. |
|
core/toolsreg
Package toolsreg assembles the set of built-in tool definitions advertised to the model.
|
Package toolsreg assembles the set of built-in tool definitions advertised to the model. |
|
core/version
Package version exposes the jungi build version.
|
Package version exposes the jungi build version. |
|
core/worktree
Package worktree manages per-session git worktrees rooted under <repo>/.jungi/state/worktrees/<id>/.
|
Package worktree manages per-session git worktrees rooted under <repo>/.jungi/state/worktrees/<id>/. |
|
hooks
Package hooks defines jungi's first-party built-in hook catalog.
|
Package hooks defines jungi's first-party built-in hook catalog. |
|
hooks/githubpr
Package githubpr implements the "github-pr" built-in hook.
|
Package githubpr implements the "github-pr" built-in hook. |
|
hooks/notify
Package notify implements the "notify" built-in hook, which sends a desktop notification on each subscribed lifecycle event.
|
Package notify implements the "notify" built-in hook, which sends a desktop notification on each subscribed lifecycle event. |
|
provider/catalog
Package catalog provides a provider-neutral view of the OpenRouter model search API for the /model search flow (see internal/tui/modelsearch and internal/tui/modelresults).
|
Package catalog provides a provider-neutral view of the OpenRouter model search API for the /model search flow (see internal/tui/modelsearch and internal/tui/modelresults). |
|
provider/client
Package client defines the provider-neutral transport contract used by jungi to talk to LLM APIs, plus the OpenRouter client implementation.
|
Package client defines the provider-neutral transport contract used by jungi to talk to LLM APIs, plus the OpenRouter client implementation. |
|
provider/message
Package message defines the Message type and the three roles a turn can occupy in a jungi conversation.
|
Package message defines the Message type and the three roles a turn can occupy in a jungi conversation. |
|
provider/model
Package model resolves model identifiers to their context limits, pricing, and reasoning capabilities entirely at runtime.
|
Package model resolves model identifiers to their context limits, pricing, and reasoning capabilities entirely at runtime. |
|
provider/model/modeltest
Package modeltest exports the canonical OpenRouter test identifiers and a Register helper that installs canned Configs for them.
|
Package modeltest exports the canonical OpenRouter test identifiers and a Register helper that installs canned Configs for them. |
|
provider/tooldef
Package tooldef defines the provider-neutral tool-definition contract.
|
Package tooldef defines the provider-neutral tool-definition contract. |
|
provider/usage
Package usage tracks token consumption and dollar cost across API requests.
|
Package usage tracks token consumption and dollar cost across API requests. |
|
ptr
Package ptr provides helpers for taking addresses of literals.
|
Package ptr provides helpers for taking addresses of literals. |
|
tools/editfile
Package editfile implements the jungi built-in edit_file tool commands.
|
Package editfile implements the jungi built-in edit_file tool commands. |
|
tools/plan
Package plan implements the plan-management tools (create_plan, add_ticket, ..., research_codebase).
|
Package plan implements the plan-management tools (create_plan, add_ticket, ..., research_codebase). |
|
tools/runshell
Package runshell implements the sandboxed run_shell tool definition and executor.
|
Package runshell implements the sandboxed run_shell tool definition and executor. |
|
tools/rununsafeshell
Package rununsafeshell implements the run_unsafe_shell tool — an unsandboxed shell executor that requires user approval before running.
|
Package rununsafeshell implements the run_unsafe_shell tool — an unsandboxed shell executor that requires user approval before running. |
|
tools/skill
Package skill implements all skill-related tools: load_skill, read_skill_file, and run_skill_script.
|
Package skill implements all skill-related tools: load_skill, read_skill_file, and run_skill_script. |
|
tools/tasklist
Package tasklist implements the task-list tools (create_task_list, add_task_to_task_list, update_task, update_task_list_status, get_task_list).
|
Package tasklist implements the task-list tools (create_task_list, add_task_to_task_list, update_task, update_task_list_status, get_task_list). |
|
tools/tool
Package tool defines the shared contract every built-in tool implements: a Definition advertised to the model and an Execute that runs a single invocation and returns a uniform Result.
|
Package tool defines the shared contract every built-in tool implements: a Definition advertised to the model and an Execute that runs a single invocation and returns a uniform Result. |
|
tools/uselsp
Package uselsp exposes the provider-neutral tool definition and Tool implementation for the built-in `use_lsp` tool.
|
Package uselsp exposes the provider-neutral tool definition and Tool implementation for the built-in `use_lsp` tool. |
|
tools/webfetch
Package webfetch implements the SSRF-safe HTTP fetch primitive used by the web_fetch tool.
|
Package webfetch implements the SSRF-safe HTTP fetch primitive used by the web_fetch tool. |
|
tui
Package tui implements the terminal user interface for the jungi chat application.
|
Package tui implements the terminal user interface for the jungi chat application. |
|
tui/approvalview
Package approvalview implements the tool confirmation overlay.
|
Package approvalview implements the tool confirmation overlay. |
|
tui/closeconfirmview
Package closeconfirmview implements the dirty-worktree confirmation overlay shown when /close or /clear would destroy uncommitted or unpushed work.
|
Package closeconfirmview implements the dirty-worktree confirmation overlay shown when /close or /clear would destroy uncommitted or unpushed work. |
|
tui/cmdpalette
Package cmdpalette implements the slash-command palette overlay.
|
Package cmdpalette implements the slash-command palette overlay. |
|
tui/credpicker
Package credpicker implements a radio-button style overlay for selecting which provider credential to set.
|
Package credpicker implements a radio-button style overlay for selecting which provider credential to set. |
|
tui/history
Package history provides a scrollable transcript of the conversation.
|
Package history provides a scrollable transcript of the conversation. |
|
tui/input
Package input provides the multi-line text entry component used at the bottom of the chat UI.
|
Package input provides the multi-line text entry component used at the bottom of the chat UI. |
|
tui/modelpicker
Package modelpicker implements the overlay that lists locally cached models so the user can switch the active session's model.
|
Package modelpicker implements the overlay that lists locally cached models so the user can switch the active session's model. |
|
tui/modelresults
Package modelresults implements the overlay that lists OpenRouter models returned by a modelsearch query.
|
Package modelresults implements the overlay that lists OpenRouter models returned by a modelsearch query. |
|
tui/modelsearch
Package modelsearch implements the /model overlay shown when the user picks the OpenRouter provider: a small editable form of search filters that gets translated into a catalog.Query and handed off to the OpenRouter models API.
|
Package modelsearch implements the /model overlay shown when the user picks the OpenRouter provider: a small editable form of search filters that gets translated into a catalog.Query and handed off to the OpenRouter models API. |
|
tui/newsessionconfirmview
Package newsessionconfirmview implements the confirmation overlay shown when the user starts a new session (via /new, /plan, /execute, /review, or the /sessions list "New session" item) while a session is already active.
|
Package newsessionconfirmview implements the confirmation overlay shown when the user starts a new session (via /new, /plan, /execute, /review, or the /sessions list "New session" item) while a session is already active. |
|
tui/optionspicker
Package optionspicker implements the /options overlay.
|
Package optionspicker implements the /options overlay. |
|
tui/overlay
Package overlay composites a foreground widget centred over a background terminal grid.
|
Package overlay composites a foreground widget centred over a background terminal grid. |
|
tui/planpicker
Package planpicker implements the overlay shown when the user runs /execute without a slug argument.
|
Package planpicker implements the overlay shown when the user runs /execute without a slug argument. |
|
tui/promptpicker
Package promptpicker implements the overlay shown when the user runs /prompt.
|
Package promptpicker implements the overlay shown when the user runs /prompt. |
|
tui/reasoningpicker
Package reasoningpicker implements the /reasoning overlay.
|
Package reasoningpicker implements the /reasoning overlay. |
|
tui/sessionlist
Package sessionlist implements the overlay shown when the user runs /sessions.
|
Package sessionlist implements the overlay shown when the user runs /sessions. |
|
tui/styles
Package styles defines the lipgloss color and layout constants shared across the TUI.
|
Package styles defines the lipgloss color and layout constants shared across the TUI. |
|
tui/ticketpicker
Package ticketpicker implements the overlay shown after the user selects a plan from the plan picker during /execute.
|
Package ticketpicker implements the overlay shown after the user selects a plan from the plan picker during /execute. |
Click to show internal directories.
Click to hide internal directories.