.skills]` overlays per-skill toggles for that role.
- Use `"quoted names"` to refer to skill keys containing spaces.
# Contributing
Kent is intentionally narrow and opinionated. We value changes that improve reliability, output quality, reviewability, and long-term maintainability. The best contributions are focused, technically coherent, and aligned with the product direction.
## Start With an Issue
External contributions should begin with an issue before a pull request is opened.
This helps avoid wasted work and gives maintainers a chance to confirm scope, approach, and fit. Once the issue has been triaged, a PR is welcome.
Changes are less likely to be accepted if they add broad configurability, plugin-style surface area, extra UI chrome, or product direction that conflicts with the repository's design principles.
## Product Boundaries
Kent is intentionally narrow. Feature proposals are expected to improve reliability, output quality, observability, long-running work, or composability without adding avoidable model burden.
These directions are part of the current product boundary and are unlikely to be accepted:
- **Native in-process subagent orchestration.** Use separate headless Kent runs through `kent run`, named subagent roles, shell scripts, tmux, or background shells. Keeping side agents as normal Kent processes makes them scriptable, inspectable, resumable, and easy to kill.
- **Plan mode as a dedicated product surface.** Frontier models can already plan, revise, and ask questions. Kent should not add a UI mode that constrains the model or encourages ceremonial planning output.
- **MCP as a first-class integration surface.** Kent prefers a small model-facing tool set and normal CLI programs. If a capability can be exposed as a command-line tool or script, that is usually the better integration path.
- **Extra UI chrome or vibe-coding surfaces.** Kent's UI should stay focused on terminal-native engineering work: steering, inspection, review, session control, and long-running execution.
- **Runtime toolset or model switching for active sessions.** Changing these mid-session can invalidate prompt caches and alter the model contract. Prefer per-session config, subagent roles, or new sessions.
- **Microcompaction.** Compaction should preserve continuity and cache behavior. Tiny frequent rewrites add cost and risk without enough benefit.
- **Built-in sandboxing as a trust boundary.** Sandboxing should be done with real isolation such as containers, VMs, or remote environments. Kent may support workflows that run inside those environments, but the CLI itself should not pretend that a fragile local sandbox is a security boundary.
- **A dedicated WebFetch tool.** Use shell-accessible tools or scripts that return raw Markdown, such as Jina Reader wrappers. This keeps web access transparent and avoids another model-facing tool.
- **Anthropic, Gemini, or Antigravity subscription usage.** These will not be supported unless their terms allow third-party harnesses. API-key or compatible-provider work should still fit the normal provider capability model.
This list is not a substitute for design review. If a proposal appears to conflict with a boundary but solves an important reliability or quality problem, open an issue and describe the tradeoff clearly before writing code.
## Development Setup
Prerequisites:
- Go `1.25`
- Just
- Node `22` or newer and pnpm for desktop and docs commands
- ripgrep (`rg`)
- Rust toolchain for Tauri native builds in `apps/desktop`
Prepare the checkout:
```bash
just setup --apply
```
## Before Opening a Pull Request
For code changes, run:
```bash
just check --dry-run
```
Use typed variants to narrow work:
```bash
just build go
just test server -- ./server/session -run TestResume
just lint docs --dry-run
just check desktop --dry-run
```
Bare `just build` builds the active Go, desktop, and docs areas. Bare `just test` runs server and desktop tests. Frozen Rust runs only through explicit `rust` variants. Native Tauri builds additionally require platform-specific WebView/build prerequisites.
## Pull Request Expectations
Please keep pull requests small enough to review in one pass and make sure they are tied to a previously triaged issue.
A strong PR usually:
- solves one clear problem
- includes tests for behavior changes
- updates user-facing documentation when needed
- keeps `AGENTS.md` accurate when project guidance changes
- avoids unrelated cleanup in the same change set
Draft PRs are fine when they are clearly marked and linked to the issue.
## Questions
If you want to work on something and there is no issue yet, open one first. If an issue already exists, use that thread to discuss the work.
## AI Code Policy
AI-generated code is absolutely acceptable, **provided it matches the quality standards** of the repo.
Fully or mostly AI-generated PRs with no or little human review that do not adhere to the current project architecture or guidance & constraints (in short, "Slop") will be closed without notice or discussion with the author of the PR being blocked and reported.
Additionally:
- Do **not** leave "co-authored by " attributions
- Disclose the use of AI in the PR authorship
- Do **not** introduce additional AI configuration files such as `.cursorrules` to the project in an unrelated PR. Editing AGENTS.md is fine and encouraged.
- Do not leave elaborate AI-generated PR descriptions. Prompt the agent to leave succinct, readable, human-like descriptions that are to the point.
# Home
Kent is a high-performance coding agent for professional Agentic Engineers focusing on output quality and long-running tasks.
Quickstart
·
Docs
·
Releases
Kent is a coding agent for professional engineers. It gives frontier coding models the features that empower them to produce their best output: from contextual reminders and harness awareness to token-optimized searches and async execution loops, then wraps that in a UI built for engineers who want to ship real products and work across multiple large codebases.
Codex and Claude Code are good defaults for quick demos and vibe-coding. Kent is for the moment you want the model to work freely but safely, for hours, on large codebases, as your pair programmer & collaborator.
Try it if you have ever lost work quality after compaction, watched an agent hide the command that mattered, babysat a long refactor with "continue" or ralph loops or fixed broken code after the agent ignored repository rules.
## Why Kent
### Keeps going when the context gets hard
Compared to other harnesses, Kent has significantly higher compaction quality with its carryover prompts and a multi-step algorithm that **lets the model decide** when and what to compact.
The expensive failure is when model half-remembers a decision, forgets an in-flight edit, or restarts a plan after a bad summary. Kent is designed to make 35+ compactions survivable.
### Quality is first-class
- Kent teaches the model to **ask you questions** instead of bulldozing through changes to produce slop. Expect to make important product decisions, learn about caveats, perform refactoring, and ship high-quality code with Kent.
- Kent runs a **customizable supervisor agent** in parallel with the main agent. The supervisor reviews the agent's changes and steers it to follow instructions and do its best work.
- Subagents are real Kent runs. The model delegates to **customizable agent roles, runs everything in async shells**, sleeps and wakes up in a natural, **0-token ralph loop** until the task is done, no matter the scope.
### Token-efficient & cheap
- Smart tool processing. Use **built-in shell optimizers** natively or **connect tools like `rtk`**, and unlike other popular coding agents, the model controls how the output is optimized.
- Unlike harnesses which overload models, Kent ships just **three tools** that enable the model to do everything: `patch`, `shell`, and `ask`. Everything else is smart, contextual, composable, non-blocking.
- Efficient shells. **Tools run async** with the main model: no timeouts, no retries, and compact file-based inspection of shell outputs lead to **1.6-2x token savings**.
- Cache invalidation tracking. Unlike some harnesses that drain your limits in minutes due to a caching bug, with Kent **you know about every unwanted cache miss**. Not that they will happen, with Kent's **snapshot-based cache preservation** mechanisms.
- **Shell-native, scriptable search/read stack** with optimized `rg` config enables **40% more efficient searches** instead of clunky Search, Glob, Grep, Read, Scroll chains.
### Everything is customizable & transparent
- Unlike popular harnesses, Kent supports customizing **subagent roles**, **compaction algorithms**, web search, supervisor and main model **system prompts**, skills, tools, reminders, caching, and more.
- With local overrides of everything, create **per-project system prompts**, skill bundles, subagent roles and share the setup with your team via a single `.toml` file.
- The default UI is **fast, non-flickering, native transcript**. Unlike some providers, Kent's detailed mode lets you **inspect every input and output** so there's no surprises, ever.
### True Sandboxing & Parallelization
- Kent runs a single 50mb **server process that orchestrates all your agents** & shells. Unlike other harnesses which embed an unreliable custom sandbox, you can run Kent **completely isolated** (e.g. via Docker) and connect to it from your favorite terminal - no SSH, no tmux.
- Git worktrees are first-class. Run 10+ agents in parallel via **auto-managed worktrees with customizable setup logic**. Unlike other harnesses, the agent knows how to handle the worktree and won't break your repo.
## Philosophy
Kent is intentionally narrow. It optimizes for engineers who want collaborative workflows, token efficiency, and quality outputs. As such, there will not be:
- MCP support; MCP is suboptimal for shell-enabled agents, use [mcporter](https://github.com/openclaw/mcporter) or native CLIs.
- Plan mode; just prompt the model to plan with you. Kent is built for collaborative work and can plan without any explicit nudges or restrictions.
- WebFetch tool; teach the agent to use [r.jina.ai](https://github.com/respawn-llc/kent/blob/main/jina.ai/reader), browser control CLI, or curl.
Ready to try? Head over to the [quickstart](https://kent.sh/quickstart/) guide.
## Why no Anthropic/Gemini model support?
- Anthropic and Gemini disallow use of third-party harnesses with subscriptions. Using them can get you banned, asking for their support will get people behind Kent sued. Please do not ask for support here.
- Using models with API keys can be supported, but the priority is low due to high costs of testing and significant effort to optimize the harness for different models. Please create or upvote an issue if you want to use Kent with a new provider or model. Kent already supports OpenAI Responses-compatible APIs, local models, and OpenAI API keys.
## License
Kent is licensed under `AGPL-3.0-only`. See [LICENSE](https://github.com/respawn-llc/kent/blob/main/LICENSE).
# Headless runs
> Headless Kent runs, scriptable output modes, and how interactive Kent uses the same mechanism for subagents.
Kent supports a headless, non-interactive run mode via `kent run`.
When the interactive Kent session uses subagents, it does so by launching separate headless Kent runs.
This keeps the subagent path contextual and scriptable: subagent invocations are not new tools and consume no extra tokens in model context.
Run a single prompt:
```bash
kent run --agent fast "summarize the unstaged changes in this repo"
```
Continue an existing headless session:
```bash
kent run --continue ""
```
Control an active shared run from another shell or agent:
```bash
kent run steer "adjust the next step" # steer a running agent
kent run stop # gracefully interrupt the run
kent run wait # wait for the model's turn to end
kent run watch # report the next question or terminal outcome
```
When a human invokes `kent run steer`, the running Session receives a user message. When another Kent Session invokes it, the running Session receives a developer-role agent steer that identifies the source Session and includes the command form for replying.
Headless `kent run` Sessions cannot create Questions. To inspect or answer a pending Question from an interactive or Workflow Session:
```bash
kent question --session
kent question answer --session --option 1 --commentary "Additional context"
kent questions --task KENT-335
kent questions answer --task KENT-335 --commentary "Freeform answer"
```
Workflow Tasks can be observed without polling:
```bash
kent task wait KENT-335
kent task watch KENT-335
```
List answered Questions from one Session, newest first:
```bash
kent questions list --session
kent questions list --session --max-handoffs 1 --json
```
`--max-handoffs` defaults to 25 and counts the current unfinished history window. Question history reads the Session log and can be slow, especially in JSON mode. A Task may retain hundreds of Sessions; use `kent task sessions ` to choose a Session before listing its Question history.
These commands are one-shot server-side waits. `wait` ignores Questions but reports the next interruption, error, or terminal completion; `watch` reports the next Question, interruption, error, or terminal completion. A reported Question includes a runnable `kent question answer` command.
Use exactly one of `--session` or `--task`. Task short IDs resolve in the current workspace's Project unless `--project` selects another Project. A Task with pending Questions in several Sessions is ambiguous; Kent answers nothing and lists each candidate Session name and ID.
:::tip
`kent run` needs a server connection to keep long-running shells and agents properly orchestrated. If you want to script kent runs, make sure the [Server](../server/) is running.
:::
## Subagent Roles
Roles are needed to create specialized subagent types for different tasks and workflows. Treat them like different employees or specialists.
`--agent ` selects a named subagent role from `[subagents.]` in the local or global config file. `--agent default` clears a resumed role and uses the base settings; `none` and `self` are not run-agent selectors.
To open an interactive session with a role, run:
```bash
kent --agent research
```
To apply a role while reopening a specific session, combine it with `--session` or `--continue`. Unlocked sessions may select another role or clear the role with `--agent default`. If the session has a locked model request shape, the selected role must match the persisted role and `--agent default` cannot clear it.
Example subagent config:
```toml
[subagents.research]
model = "gpt-5.6-sol"
thinking_level = "xhigh"
system_prompt_file = "research-agent.md"
description = "Use when you need fast, smart general-purpose researcher for deep thinking or complicated plans."
priority_request_mode = true
agent_callable = true
workflow_subagent = true
[subagents.research.tools]
patch = false
[subagents.research.skills]
"kent-dogfooding" = false
```
- Set `agent_callable = false` to disallow agents to call that subagent role on their own.
- Set `workflow_subagent = false` to disallow workflow agents from calling that custom role.
- The built-in `fast` role exists even without config.
- Subagent roles inherit the main config and then override only the keys you set in that role table.
Useful role-specific keys include:
- `model`, `provider_override`, `openai_base_url`, etc.
- `thinking_level`, `model_verbosity`, `priority_request_mode`
- `system_prompt_file`
- `description`, `agent_callable`
- `workflow_subagent`
- `[subagents..tools]`
- `[subagents..skills]`
For the full list of shared overrides, see [Configuration](../config/).
## Delegation Depth
Kent limits model-originated creation of new child agents. A root session is depth `0`; with the default maximum of `2`, a root can create a subagent at depth `1`, that subagent can create one at depth `2`, and creation of a child at depth `3` is rejected.
The same limit applies across role changes and to delegation initiated by workflow agents. Scheduler-created workflow sessions start at depth `0`. Derived sessions such as `/new`, `/review`, rollback forks, and workflow fan-out clones preserve their source's agent ancestry.
The policy applies only when creating a new model-originated child. Opening or continuing an existing session is unchanged. Kent reads the active effective configuration for each attempt, rejects an over-limit launch before creating its session, and tells the current agent to stop trying subagents and complete the task itself.
Configure the root-level TOML key, supported range, and disable-with-zero behavior in the [configuration reference](../config/#core-settings). There is no environment-variable or `kent run` flag override.
## Session Behavior
Headless runs are non-interactive. They do not stop to ask the human operator questions mid-run, issue tool preambles, or support the Supervisor. That makes them more suitable for background execution, automation, and saves tokens. You can talk to a headless agent if you select it in the `/resume` (session picker).
### Provider usage history
Successful provider operations retain one usage observation in Session history. Each observation includes the operation identity and originating Session identity, operation purpose and time, requested and served provider/model details, provider response identity when available, provider-reported usage and metadata, and hosted-tool evidence.
Usage observations retain provider data for external price lookup; Kent does not calculate monetary costs, fetch prices, or expose Session totals. Missing provider fields and usage from earlier history remain absent rather than representing zero consumption, and copied history preserves the original operation identity.
Only provider operations that return successfully through the model transport are observed. Failed, interrupted, or incomplete operations, provider omissions, and process termination can leave the retained history incomplete.
## Workspace Binding
Headless runs fail if the selected workspace is not already attached to a Kent project.
This is needed to enable functionality related to project management and allows remote execution, but sometimes comes as a limitation where you want to run subagents in different repos. To fix the error, you simply need to approve workspace (git repo, folder etc.) binding:
- `kent project` prints the project id for the bound workspace at `path` or `cwd`. Use to learn project IDs.
- `kent attach ` attaches another workspace at [path] to the project already bound to `cwd`.
- `kent attach --project [path]` attaches using the ID.
- `kent detach --project [path]` removes one workspace binding from that project. The path defaults to the current directory; use `--workspace ` when the saved path is inaccessible or missing.
- `kent project default --project [path]` changes the project's default workspace. It accepts the same path or workspace-ID selector and applies immediately.
- `kent rebind ` retargets a session while keeping its source project and attaches an unbound target workspace to that project.
- `kent rebind --project ` moves a non-workflow session to another project and attaches an unbound target workspace.
For a live session, Kent acknowledges the scheduled move and applies it between agent steps, preserving the running agent and queued input even across projects. Existing background commands continue in their original directories; new commands use the destination. Dormant session moves complete synchronously and reject running session-owned background commands.
Detach and default-workspace selection require an explicit project ID. Path selectors are converted to absolute server paths before the request. A shared path can be detached from one project without changing its binding in another project.
Use `--json` for automation. Successful detach returns `status: "ok"` with `project_id` and `workspace_id`; successful default selection returns the updated project at `result.project`. Operational failures return one `status: "error"` object with a stable error code. Detach blockers include bounded guidance; a default-workspace blocker directs you to choose another attached workspace with `kent project default`.
Detach error codes are `project_not_found`, `workspace_not_attached`, `workspace_detach_blocked`, `workspace_detach_conflict`, and `request_failed`. Default-workspace selection uses `project_not_found`, `workspace_not_attached`, and `request_failed`. JSON omits absent results, error identities, blocker counts, and retryability fields.
Detach blockers use these recovery actions:
- `default_workspace`: choose another attached workspace with `kent project default`, then retry.
- `active_sessions`: stop active runs or rebind their Sessions, then retry.
- `non_terminal_tasks`: move editable Backlog Tasks to another source workspace, or complete, manually move, or delete dependent Tasks, then retry.
- `executable_current_nodes`: stop execution and move, complete, or delete affected Tasks until no executable Current Node uses the workspace, then retry.
- `managed_owned_worktrees`: delete dependent worktrees or their quiescent owning Tasks, then retry.
- `missing_history_snapshot`: re-save the editable Task's source workspace; keep the binding if its history cannot be edited.
### Project deletion
Delete a Project by its canonical Project ID:
```bash
kent project delete --confirm
```
Project deletion is non-interactive and accepts only the canonical Project ID. The command checks for unfinished Tasks before checking `--confirm`. An agent-shell invocation is human-only when the Project contains any non-terminal Task, including a Backlog Task; it reports the Project ID and does not request deletion. Task state may change before deletion is processed, and the server's deletion blockers remain authoritative.
Without `--confirm`, the command makes no deletion request. Use `--json` for automation; it emits one `status` envelope on `stdout`, with the canonical Project ID in `result.project_id` on success or `error.project_id` on operational failure. Blocked deletion preserves server blocker codes, messages, order, and positive counts. Blockers and other operational failures exit nonzero.
Stable deletion error codes are `confirmation_required`, `human_only_unfinished_work`, `project_not_found`, `project_delete_blocked`, and `request_failed`.
Project deletion never deletes or moves workspace files.
## Output Modes
By default, `kent run` writes each finalized assistant commentary or final response to `stdout` as it is committed. Use `--quiet` to suppress live output and print only the terminal result. For scripting, use JSON mode:
```bash
kent run --output-mode=json "summarize the repo" | jq
```
JSON mode emits exactly one final object on `stdout`.
```json
{
"status": "ok",
"result": "...",
"session_id": "...",
"session_name": "...",
"continue_id": "...",
"continue_command": "kent run --continue ... \"follow-up\"",
"warnings": ["..."],
"duration_ms": 1234
}
```
On failure, JSON mode emits `status: "error"` and an `error` object instead of `result`.
An over-limit child launch uses the stable `subagent_max_depth_exceeded` code and includes the attempted depth and active maximum:
```json
{
"status": "error",
"duration_ms": 0,
"error": {
"code": "subagent_max_depth_exceeded",
"message": "subagent launch rejected at depth 3 (maximum 2): ...",
"attempted_depth": 3,
"max_depth": 2
}
}
```
Because the child was never created, this response has no session ID or continuation command. Final-text mode prints the actionable policy message instead.
---
Supported run-specific flags:
| Flag | Description |
| ----------------- | ------------------------------------------------------------------------------------------------------ |
| `--timeout` | Optional run timeout such as `30s`, `5m`, or `1h`. Default is no timeout. |
| `--output-mode` | `final-text` or `json`. Default is `final-text`. |
| `--progress-mode` | `stderr` for live responses and notices, or `quiet` for final-result-only output. Default is `stderr`. |
| `-q`, `--quiet` | Shortcut for `--progress-mode=quiet`. |
| `--continue` | Continue a previous session by id. |
| `--agent` | Select a named subagent role from `config.toml`; use `default` for the base role. |
| `--fast` | Shortcut for the built-in `fast` subagent role. |
# Lifecycle Hooks
> Run a local command when an interactive terminal session changes state.
Lifecycle hooks run a local command for events observed by an interactive Kent terminal client. Each invocation receives one JSON event on stdin.
## Configuration
Add the command and any fixed arguments to the global `config.toml`:
```toml
[hooks.client]
lifecycle = ["python3", "/absolute/path/lifecycle_hook.py"]
```
The global config is `~/.kent/config.toml` unless Kent uses another persistence root. `hooks.client.lifecycle` has no workspace, environment-variable, CLI, or subagent-role override. The executable must be non-blank, as must any arguments.
The terminal client reads this setting at startup. The command inherits the client's environment and current directory.
For remote attachments, the command runs on the terminal client's machine, not the server. Desktop clients, headless runs, subagents, and server processes do not run lifecycle hooks.
Use [command post-processing](../command-postprocessing/) instead to transform `exec_command` output.
## Events
Kent sends these categories to the configured command:
| `category` | `hook_event_name` | `details` |
| ---------------- | -------------------- | ------------------------------------------------------------------ |
| `session.start` | `SessionStart` | `kind` is `new` or `resumed`. |
| `task.complete` | `Stop` | `final_answer` and `work_performed` describe the completed run. |
| `task.error` | `PostToolUseFailure` | `diagnostic` describes the runtime failure. |
| `input.required` | `PermissionRequest` | `kind` is `question` or `approval`; `summary` contains the prompt. |
| `resource.limit` | `PreCompact` | `compaction_mode` identifies the compaction mode that started. |
`category` is the canonical event name. `hook_event_name` is an OpenPeon-compatible alias.
`task.complete` requires an assistant final answer. `task.error` requires a failed runtime result. Interruptions and successful runs without an assistant final answer emit neither event.
`resource.limit` emits for every compaction start, including manual compaction.
## Payload
This `task.complete` payload shows the schema:
```json
{
"schema_version": 1,
"cesp_version": "1.0",
"scope": "client",
"category": "task.complete",
"hook_event_name": "Stop",
"occurred_at": "2026-07-20T10:15:30Z",
"focused": false,
"context": {
"session_id": "4f44b818-e9d5-4ff4-a4ab-b9bc03bb776f",
"session_title": "Review API changes",
"workflow_task_id": "ENG-42"
},
"details": {
"final_answer": "The requested changes are complete.",
"work_performed": true
}
}
```
`schema_version` identifies the Kent payload schema. `cesp_version` and `hook_event_name` provide OpenPeon compatibility.
`occurred_at` is a UTC timestamp. `focused` reports whether the terminal client had focus when it observed the event. `context` includes the session ID, session title, and workflow task ID when available; absent values are omitted.
Payloads do not include filesystem paths, transcript history, tool input, command output, hidden reasoning, credentials, or internal runtime identifiers.
## Delivery
Delivery is asynchronous and best-effort. Events are not persisted or retried, bursts may drop events, and invocations may overlap or complete out of order.
Each invocation has a 30-second timeout. Kent ignores stdout. Launch failures, non-zero exits, and timeouts produce a terminal notice using up to 4 KiB of stderr. Repeated failures may be combined into one notice with the total count and latest diagnostic. A failure does not disable the hook.
Closing the session cancels running hook commands without waiting for them; descendant processes may continue. Hook output and failures do not change agent or server behavior.
# Prompts
> Prompt customization files, precedence, placeholders, and session snapshot behavior.
Learn how to customize system prompts, supervisor instructions, subagent system prompts, workflow prompts, and repo guidance.
Models will follow the instructions by role: `system -> developer -> user`, from most authoritative to least authoritative. With kent, you can customize all three levels:
## Instruction Files
- `~/.kent/AGENTS.md` is a global instructions file injected into every session automatically.
- `/AGENTS.md` adds developer instructions that are specific to the current project.
These files are `developer`-level instructions.
## System Prompt
System prompt files replace Kent's built-in default "product engineer" / SWE-focused system prompt. Priority, lowest to highest:
- Built-in system prompt
- `~/.kent/SYSTEM.md`
- `~/.kent/config.toml` `system_prompt_file`
- `/.kent/SYSTEM.md`
- `/.kent/config.toml` `system_prompt_file`
- Selected `[subagents.]` `system_prompt_file`
`system_prompt_file` paths are resolved relative to the containing `config.toml` directory unless absolute.
Kent snapshots the rendered system prompt on each compaction to prevent cache misses. Edits to system prompt files take effect after a successful compaction and the next model request.
## Goal Continuation
After successful automatic, manual, or handoff compaction, a non-workflow session with an active goal resumes with the exact goal text and Kent's goal work and completion guidance. Paused, completed, cleared, and absent goals add no continuation guidance, and reopening a session without compaction does not add it.
## Placeholders
You can assemble your own system prompt from building blocks provided by Kent. It's highly recommended to leave the instructions about the harness (`HarnessWorkflowAutonomy`) intact.
System prompt files use Go template syntax with these fields:
- `{{.DefaultSystemPromptHarnessWorkflowAutonomy}}` - important guidelines on harness behavior, environment constraints, available tools.
- `{{.DefaultSystemPromptPersonality}}` - Kent agent identity, communication style, and engineering posture.
- `{{.DefaultSystemPromptAmbiguityAndOutputQuality}}` - opinionated product ambiguity handling and implementation quality rules.
- `{{.DefaultSystemPromptFinalAnswerAndFormatting}}` - final response, Markdown, and formatting rules suitable for TUI.
- `{{.DefaultSystemPrompt}}` - full text of the built-in Kent system prompt.
- `{{.LaunchCommand}}` - Kent executable command, e.g. `path/to/kent.exe`.
- `{{.EstimatedToolCallsForContext}}` - estimated function/tool-call budget before compaction/handoff, exact number that varies with model context window, like `185`.
- `{{.EditingToolName}}` - name of the tool the agent uses to modify files, like `edit` or `patch`. Varies per model.
Example:
```md
{{.DefaultSystemPromptPersonality}}
{{.DefaultSystemPromptHarnessWorkflowAutonomy}}
# Team Rules
Prefer small, reviewable commits.
```
Additionally, if `tool_preambles = true` in the [config](../config/), another block of text is appended instructing the model to talk to you while working.
## Supervisor System Prompt
`reviewer.system_prompt_file` replaces Kent's built-in supervisor system prompt:
- `~/.kent/config.toml`
- `/.kent/config.toml`
The workspace config value takes priority. Kent snapshots the rendered supervisor prompt independently when a supervisor request is built; edits take effect for supervisor requests after successful compaction.
# Quickstart
> Install Kent, authenticate on first launch, tune the most useful settings, and learn the main session workflows.
## 1. Install Kent Server and CLI
#### Homebrew (macOS Apple Silicon/Linux)
```bash
brew tap respawn-llc/tap
brew install respawn-llc/tap/kent
```
#### Arch Linux (AUR)
The [`kent-bin`](https://aur.archlinux.org/packages/kent-bin) AUR package is community-maintained.
```bash
yay -S kent-bin
```
#### Standalone binaries via GitHub Releases
These versions are **not auto-updated**. Please keep them updated manually by re-running install scripts.
Linux:
```bash
curl -fsSL https://kent.sh/install.sh | sh
```
Windows:
```powershell
irm https://kent.sh/install.ps1 | iex
```
Check the installed version with: `kent --version`
## 2. Optional: Install the Background Service
Run this if you want one shared Kent server to start at login:
```bash
kent service install
```
It uses 20 MB of RAM when idle, lets unlimited frontends stay lightweight by connecting to **one** orchestrator, makes spawning and controlling subagents and background shells reliable, and enables the use of the desktop app. See [Kent Server](../server/) for details and service management commands.
## 3. Install Kent Desktop
The desktop app lets you use Kent's [Workflows and Tasks](../workflows/) feature to build agentic loops and deterministic pipelines to **fully automate** processes and scale to 10s or 100s of agents.
### Manual Install
Download the installer for macOS Apple Silicon, Linux x86_64, or Windows x64 at [kent.sh/desktop](https://kent.sh/desktop), or install the macOS app via Homebrew:
```bash
brew install --cask respawn-llc/tap/kent-desktop
```
Homebrew installs update through `brew upgrade`, standalone installs self-update.
On macOS and Linux, drag local files into Kent Desktop to insert their absolute paths into the focused text input. This inserts text, not attachments. Drops without a focused editable input, and file drops on Windows or in a browser, are ignored.
:::note
The desktop app, due to the asynchronous nature of workflows, needs a [server](../server/) to connect to.
:::
# First Use
:::danger[Security Warning]
Out of the box, Kent does not ship a sandbox, and does not enforce tool calling permissions. **Using Kent is equivalent to running `claude --dangerously-skip-permissions` or `codex --yolo`.** The model will have **full access** to your entire computer. By using Kent, you accept full responsibility for what the model does on your computer. If you want to safely run Kent in a real sandbox, see [Sandboxing](../sandboxing/).
:::
Start Kent CLI with: `kent`. The first run will ask you to pick auth option and walk you through onboarding.
The session picker shows when a newer Kent server release is available; update Kent through the installation channel you used.
Supported auth options:
- OpenAI/Codex subscription OAuth via the startup sign-in picker.
- OpenAI-based API-key auth via `OPENAI_API_KEY`. If you prefer API-key auth, export `OPENAI_API_KEY` before launch and kent will ask to use it.
- No auth for custom providers. This option supports any provider like `ollama`, `omlx` local models, or third-party providers like GLM coding plan. The only requirement is that the provider supports the OpenAI Responses format.
:::note
Anthropic or Gemini subscriptions/models will not be supported until these companies allow third-party harnesses in their ToS.
:::
## Main Workflows
- Press `F1` to invoke the help menu.
- Use `Enter` to steer the model, `Tab` to queue messages. Slash commands can be queued too!
- Use `Shift+Tab` to toggle between detailed transcript mode and lean ongoing mode.
- Type `$ ` to execute a shell command and show its output to the model.
- Press `Esc` twice to enter Edit mode, which lets you go back in time, edit a previous message, and fork the session starting with it. Use `Up`/`Down` to walk through user messages. File edits are **not** rolled back.
- Use the `Up`/`Down` arrow keys to select and resend previous prompts.
- Press `Ctrl+V`, `Ctrl+D`, `Alt+V`, or `Alt+D` to paste clipboard content: images become temporary file paths and text is inserted at the cursor. Terminal-native bracketed paste remains normal text input.
- Use `/review` to start a code review. In a non-empty session, Kent opens that review in a fresh child session. After the review finishes, you can use `/back` to teleport to the original session.
- `/name ` will set your session name in the picker and terminal title.
- `/autocompaction` will toggle compaction, and `/compact` will trigger one. If autocompact is off, you can go above 100% context usage if model allows it. **Going above 100% will cost more and degrade model performance**.
- Run `/status` to get detailed info about the session.
For the full command reference, see [Slash Commands](../slash-commands/).
## Configuration
Kent reads settings from `~/.kent/config.toml`. The full reference is on the [Configuration](../config/) page.
## Skills and Slash Commands
On first launch, the setup wizard can optionally import existing skills and slash-command directories from supported providers.
Kent discovers skills from:
- `/.kent/skills`
- `~/.kent/skills`
- `/.generated/skills`
The generated root is managed by Kent. Copy a generated skill into a workspace or global skill root before customizing it.
You can disable skills for new sessions in `config.toml`:
```toml
[skills]
creating-skills = false
```
Changes take effect when a session starts or after compaction.
Custom slash commands are server-owned and appear in the picker with 256-character previews. See [Slash commands](../slash-commands/) for discovery precedence, argument expansion, and unavailable-command behavior.
## Supervisor
- Use `/supervisor` to toggle its invocation for the current session. Supervisor is a feature that will automatically review the edits made by the model. It increases costs by ~15% (if using the main model) but improves results. By default supervisor uses the same model as the main one. That may be too costly / too slow for you. [Configuration](../config/) page contains instructions on how to change supervisor model.
## Advanced
Once you're comfortable driving the traditional agentic CLI, consider upgrading to [workflows](../workflows/).
# Sandboxing and Security
> Kent's default trust model, outside-workspace edit prompts, and remote/container server setup.
:::warning
Kent is YOLO by default: it does not run tools inside a built-in sandbox.
The agent executes shell commands and file tools in the environment where the Kent server runs.
If that environment can read secrets, reach networks, or modify files, the agent can do the same.
:::
However, Kent's [client-server](../server/) architecture makes it easy to run Kent in a **completely isolated, secure container or VM**.
## Outside-Workspace Edits
By default, native edit tools prompt before modifying files outside the Session's Execution Target Root and the bounded collection of up to 500 most recently attached Workspaces in the Session's current Project. `view_image` uses the same trusted boundary for local image reads. Targets under the operating system's temporary roots and their canonical platform aliases, such as `/tmp` and `/private/tmp` on macOS, are allowed without approval. The temporary-root allowance does not override path-deny rules or the prohibition on directly editing another Kent-managed Worktree. Kent prepares this boundary once for the runtime; native file operations do not query Project metadata for each target.
**This is not sandboxing: the agent can easily bypass this.** It's intended for convenience, hallucination and mismatched working-directory prevention. Edits to another Kent-managed Worktree remain forbidden even when that Worktree belongs to the same Project.
To disable, set config:
```toml
allow_non_cwd_edits = true
```
## Server Boundary
Kent separates frontend clients from the server that owns all of the work. That split makes the server environment the useful security boundary:
- Run `kent serve` on a VM and connect from your laptop.
- Run `kent serve` in Docker and expose only the Kent port.
- Run several isolated servers on different ports for different trust zones.
Consequently, when you create or attach a project against a remote/container server, the workspace path must exist inside that server environment, **not on the client machine**.
## Container Image Shape
A Kent sandbox image should contain:
- A `kent` binary compatible with the client version you use.
- Mandatory server dependencies: shell, `rg` and `git`, for normal operation of the server.
- A `config.toml` file with your setup.
- Optional tools the agent may need: language toolchains, package managers, `rg`, `fd`, `jq`, `patch`, `curl`, `gh`, `wget`, `python` and project-specific CLIs.
- An (ideally persistent) workspace directory such as `/workspace`.
- A writable Kent persistence root, usually under the sandbox user's home.
- Network policy that matches the task; disable or restrict egress when needed.
Avoid mounting your host home directory, full ~/.kent/, or broad source trees into the sandbox.
Mount only the workspace, caches, and credentials the task needs.
## Example Dockerfile
This is a generic starting point.
Add the language runtimes and project tools your workflows need.
```dockerfile
FROM debian:bookworm-slim
ENV DEBIAN_FRONTEND=noninteractive
ENV HOME=/home/kent
ENV SHELL=/bin/bash
ENV KENT_VERSION=
RUN apt-get update \
&& apt-get install -y --no-install-recommends \
bash \
ca-certificates \
curl \
fd-find \
file \
git \
jq \
less \
netcat-openbsd \
openssh-client \
patch \
procps \
python3 \
python3-pip \
python3-venv \
ripgrep \
tar \
tini \
unzip \
xz-utils \
zip \
&& ln -sf /usr/bin/fdfind /usr/local/bin/fd \
&& useradd --create-home --shell /bin/bash kent \
&& mkdir -p /workspace /home/kent/.kent \
&& chown -R kent:kent /workspace /home/kent
SHELL ["/bin/bash", "-o", "pipefail", "-c"]
RUN curl -fsSL https://kent.sh/install.sh \
| KENT_PREFIX=/usr/local KENT_VERSION="${KENT_VERSION}" sh
USER kent
WORKDIR /workspace
EXPOSE 53082
ENTRYPOINT ["tini", "--"]
CMD ["kent", "serve"]
```
The image installs the latest release by default.
Build with `docker build --build-arg KENT_VERSION=vX.Y.Z -t kent-sandbox .` if you need to pin one Kent release.
Package-manager cache cleanup is useful for smaller images but omitted here for clarity.
Run the server so it listens inside the container and is reachable from the host:
```bash
docker run --name kent-sandbox --rm -it \
-p 127.0.0.1:53082:53082 \
-e KENT_SERVER_HOST=0.0.0.0 \
-e KENT_SERVER_PORT=53082 \
-v "$PWD:/workspace" \
kent-sandbox
```
In another terminal, point the local client at that server:
```bash
KENT_SERVER_HOST=127.0.0.1 KENT_SERVER_PORT=53082 kent project create --path /workspace --name sandbox
KENT_SERVER_HOST=127.0.0.1 KENT_SERVER_PORT=53082 kent
```
The project path is `/workspace` because that is the path visible to the server.
# Security
Please report security issues privately.
Do not open a public GitHub issue for an unpatched vulnerability.
For Kent's default tool trust model and container/VM isolation guidance, see the [Sandboxing and Security guide](https://kent.sh/sandboxing/).
## Reporting a Vulnerability
Use one of these private channels:
- `hello@respawn.pro`
- GitHub private vulnerability reporting.
If you are unsure whether something is security-sensitive, report it privately first.
## What to Include
Please include as much of the following as possible:
- affected version, tag, or commit
- impact and attack scenario
- clear reproduction steps or proof of concept
- relevant environment details
- whether the issue is already publicly known
Reports that are concrete and reproducible are much easier to triage quickly.
## Response Expectations
We aim to acknowledge security reports within 7 days and follow up on a best-effort basis until resolution.
We do not currently publish a fixed remediation SLA.
## Supported Versions
Security fixes are handled on a best-effort basis for the latest release and the current `main` branch.
Older versions may be asked to upgrade instead of receiving backported fixes.
## Scope
Examples of issues that should be reported through the private security process include:
- credential disclosure
- authentication or session-handling flaws
- unsafe file access or workspace-boundary bypasses
- command-execution vulnerabilities
- supply-chain or release-integrity issues
## Disclosure
Please allow maintainers a reasonable opportunity to investigate and ship a fix before public disclosure.
Once a fix is available, we may coordinate timing for public disclosure and release notes.
## Bug Bounty
There is currently no bug bounty program.
# Kent Server
> Kent's local client-server architecture and background service management.
Kent runs all its work through a local server process. Frontends are clients: TUI, desktop app, headless runs, and other local integrations all need the server to be running. To start the server, run `kent serve`.
The server owns all long-running work: sessions, projects, runtime orchestration, background shells, tool execution, tasks, workflows, and storage.
While annoying at times, this:
- Gives ability to fully isolate work on another machine, VM, or container. See [Sandboxing](../sandboxing/) for remote/container setup.
- Drastically reduces resource consumption
- Allows agents to work asynchronously during workflows.
- Allows spawning agents on schedule and periodically.
- Uses only about 25 MB of RAM while idle.
## Background Service
To use Kent on your local machine more easily, consider installing a system service that will run `kent serve` for you at login:
```bash
kent service status
kent service install
kent service restart
kent service stop
kent service start
kent service uninstall
```
All service commands accept `--persistence-root` and honor `KENT_PERSISTENCE_ROOT`. The root you install with is remembered, so pass the same root on `status`/`start`/`stop`/`restart`/`uninstall` to target that instance.
### Service recovery
On Linux, status `2` suppresses automatic crash recovery for the active service-manager activation, while other exits continue restoration; macOS retains restoration after every server exit.
On Windows, an observed numeric status `2` stops the service cleanly without recovery, and every other observed numeric status continues restoration; an unexpected service-host failure retains recovery.
If Windows cannot confirm termination, the service retains ownership and neither reports `Stopped` nor launches a replacement.
If Windows confirms termination without a numeric status, the service releases the server, launches no replacement, and stops cleanly.
A human start or restart, or `kent service install` without `--no-start`, begins a new activation; `--no-start` installs without starting. A later independent operating-system, login, or service-manager activation may start the installed service again.
## Backends
| OS | Service |
| ------------ | ---------------- |
| macOS | LaunchAgent |
| Linux / WSL2 | `systemd --user` |
| Windows | Windows Service |
- On windows, `uninstall --keep-running` is not supported; the server is bound to the service and stops with it.
- Linux headless machines may need lingering enabled so the server survives logout `loginctl enable-linger "$USER"`.
## Port Conflicts
Service install/start commands refuse to change the service when Kent's configured server endpoint is already owned by a manual `kent serve` process or by a non-Kent listener.
If you started `kent serve` manually, stop that process before installing or starting the background service.
Running another server on a different configured port is fine. Kent only checks the endpoint resolved from `server_host` and `server_port`.
# Slash Commands
> Available slash commands, how their input is parsed, and how file-backed custom commands are discovered.
Press Tab to autocomplete a command, and Enter to autocomplete and send. Press Tab again when command matches fully to **queue** the command. This allows chains like `"commit" -> [Tab] -> "/compact" -> [Tab] -> "/prompts:open_pr" -> [Tab]`.
| Command | Input | What it does |
| --------------------------------------------------------------------------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `/exit` | none | Exit Kent. During active work, Kent detaches while the server continues the run. |
| `/new` | none | Start a new session without stopping active work in the current session. |
| `/resume` | none | Open the session picker without stopping active work in the current session. |
| `/login` | none | Open auth options. |
| `/compact ` | optional free-form text | Compact the current context. Trailing text is passed through as **additional** compaction instructions. Active non-workflow goals continue in the resumed context. |
| `/name ` | optional free-form text | Set the session title. Empty input resets. |
| <code>/thinking <low|medium|high|xhigh|max|ultra></code> | optional single value | Set [Thinking](/config/#thinking). Empty input shows the current level. |
| <code>/fast [on|off|status]</code> | optional single value | Toggle or inspect Fast mode; |
| <code>/supervisor [on|off]</code> | optional single value | Toggle supervisor invocation. |
| <code>/autocompaction [on|off]</code> | optional single value | Toggle auto-compaction. |
| `/status` | none | Open a page with detailed information about the config, git, runtime, and model. |
| <code>/goal [pause|resume|clear|<objective>]</code> | optional action or objective | Set or manage the current session goal (ralph-loop). Empty input opens the goal page. |
| <code>/ps [kill|inline|logs] <id></code> | optional action + id | Open the background-process picker, or manage a specific background shell. |
| <code>/wt</code> | none | Open the Worktrees page. |
| <code>/wt create</code> | none | Open the create-worktree dialog; new branches require a non-empty base ref. |
| <code>/wt switch <target></code> | required selector | Schedule entry into a worktree by id, branch, display name, or path. |
| <code>/wt leave</code> | none | Schedule a return to the main workspace. |
| <code>/wt delete [<target>]</code> | optional selector | Delete a worktree. |
| `/copy` | none | Copy the latest durable model final answer to the system clipboard. |
| `/back` | none | Return to the parent session, if present, with the child’s latest durable final answer prefilled. |
| `/review <what to review>` | optional free-form text | Trigger Kent's native code review. It reuses an empty session; otherwise it starts a fresh child session. |
| `/init <instructions>` | optional free-form text | Run repository initialization. It reuses an empty session; otherwise it starts a fresh child session. |
| `/prompt:<name>` | optional trailing arguments | Run a server-owned custom prompt command. |
Goal-started work uses ordinary chat's Question and Interrupt controls. Interrupt suspends automatic Goal continuation; `/goal resume` resumes it.
Goal changes are saved immediately, including during model work. Confirmation means the goal is saved; Kent schedules the model reminder for the next step boundary.
Kent discovers Markdown prompt commands on the server that owns the attached Project Workspace. Remote clients do not read server paths or receive prompt bodies in the command catalog.
The effective roots, in descending precedence, are:
- `<workspace>/.kent/prompts`
- `<workspace>/.kent/commands`
- `<persistence-root>/prompts`
- `<persistence-root>/commands`
- `<persistence-root>/.generated/prompts`
- `<persistence-root>/.generated/commands`
Discovery is non-recursive and includes non-blank `.md` files. The first valid file for each normalized basename wins. IDs lowercase letters, preserve digits, convert whitespace and underscores to one underscore, and discard other characters.
The picker shows a one-line preview made from the first 256 Unicode characters after collapsing whitespace. Markdown punctuation remains unchanged. Prompt bodies are resolved by the server when the command is invoked.
If the exact `$ARGUMENTS` token appears in the body, Kent replaces every occurrence with trimmed trailing arguments. Otherwise, Kent appends non-empty trailing arguments after one blank line.
First-time setup can import slash-command directories from supported providers. An unavailable or unknown `/prompt:` command reports an error and is never sent to the model as plain text. Other unknown slash commands retain their normal behavior.
During an active turn, an available `/prompt:<name>` command steers its server-expanded prompt into the current session. `/review` and `/init` retain their fresh-session behavior.
# Workflows
> Build reusable agent workflows, edit them in Kent Desktop, and run tasks through them.
Kent workflows are reusable process graphs for agent work. A workflow defines where a task starts, which agent roles work on it, which choices those agents can make, when humans approve a step, how parallel branches join, and where automation stops.
Workflows are linked to projects. Tasks live in projects, then move through the linked workflow as Kent starts sessions, manages worktrees, collects transition outputs, asks questions, waits for approvals, and records activity.
```text
Backlog -> Plan -> Implement -> Review -> Done
^ |
| v
+----- Needs changes
```
## 1. Choose How To Build
### Ask Kent To Create It
The easiest path is to ask Kent to model your existing work process as a workflow. Kent agents can inspect your repo, agent roles, skills, slash commands, project conventions, and past sessions, then create the reusable workflow definition for you. After that, use Kent Desktop to review and adjust the graph.
Example prompt:
```md
Use the Kent workflows skill. Study my existing Claude Code/Codex data: agent configurations, slash commands, skills, and session logs that represent my real workflow. Turn that work process into an automated Kent workflow for this project.
Include the roles, nodes, transitions, prompts, parameters, context modes, approvals, and completion modes you recommend. Link it to this project, set it as the default if it is ready, and tell me what I should review in the desktop workflow editor.
```
This path works best when you describe the real decision points in your process: when implementation is done, what a review must return, when QA is required, what counts as shipped, and where you want explicit approval.
### Build Or Edit In Kent Desktop
Use Kent Desktop when you want direct control over the workflow definition.
From a project, create or link a workflow, open the workflow editor, then edit the graph. Agent-generated workflows follow the same path: review the workflow, fix validation issues, adjust prompts, save, and run tasks from the project board.
## 2. Set Up Agent Roles
Workflow Agent Nodes run existing Kent subagent roles. Each Agent Node requires a concrete configured fallback Assignee, and that fallback role must effectively enable `ask_question`; see [Tools](../config/#tools) for tool configuration.
Roles hidden from workflow-agent delegation remain valid Node Assignees.
Eligible serial transitions into Agent Nodes can select an Assignee from roles explicitly configured with `agent_callable = true`; Kent force-enables `ask_question` for that transition-selected execution, and `workflow_subagent` does not restrict the selection.
```toml
[subagents.implementer]
description = "Implements approved tasks and leaves reviewable changes."
model = "gpt-5.6-sol"
thinking_level = "high"
system_prompt_file = "agents/implementer.md"
agent_callable = false # prevent ordinary Kent sessions from delegating to this role
[subagents.reviewer]
description = "Reviews changes and returns actionable findings."
model = "gpt-5.6-sol"
thinking_level = "xhigh"
system_prompt_file = "agents/reviewer.md"
workflow_subagent = false # prevent workflow agents from delegating to this role
```
See [Headless runs](../headless/#subagent-roles) for the role configuration reference.
## 3. Understand The Graph
### Workflow, Project, And Task
- A workflow is the reusable graph definition.
- A project links workflows, provides workspaces, and owns the task board.
- A task is the durable unit of work that moves through one workflow.
- A task directly owns its Current Nodes: normally one node, or several while a transition fans out into parallel branches. Current Nodes have no independent identity.
- An Agent Current Node can bind to a retained Kent Session. A Script Current Node has no Session and retains only the state needed to resume its script.
Creating a task puts it in Backlog. Starting the task applies the workflow's start transition and creates its first executable Current Node. Leaving a node removes its execution state; retained Sessions remain available to the task.
### Nodes
Nodes are workflow states. Visible executable and terminal nodes become board columns.
| Node kind | Use |
| --------------- | --------------------------------------------------------------------------------------------------------- |
| Start / Backlog | Where tasks rest after creation. Each workflow has one start node. |
| Agent | Runs a Kent agent using the selected subagent role. |
| Script | Executes a local script on the Kent server and parses stdout as workflow completion JSON. |
| Join | Waits for parallel branches and aggregates their parameters. Joins are graph plumbing, not board columns. |
| Terminal | A sink where automation stops, commonly Done. |
Keep node keys stable and machine-friendly, such as `plan`, `implement`, `review`, `needs_changes`, and `done`. Keys are used by agents, prompts, and validation, so prefer lower-case letters, numbers, and underscores over display labels with spaces.
### Transitions
A transition is a choice an agent can make when it completes a node. A transition has a human label, a stable key, and a model-facing description that tells the source agent when to choose it.
In graph terms, one selectable transition is a transition group, and each branch is an edge to a target node.
Each transition contains one or more branches:
- A normal transition has one branch to one target node.
- A fan-out transition has multiple branches and starts parallel work.
- A branch into an agent node carries that target agent's prompt, context mode, approval setting, and parameters.
Use transition descriptions for choice criteria. For example, a Review node might offer `done` with "Choose when the implementation is correct and ready to ship" and `needs_changes` with "Choose when implementation changes are required."
### Parallelism, Node Groups, And Joins
Use a node group when one source agent should fan out into parallel branches. Parallel branches are ordinary workflow nodes, not subtasks: one task temporarily owns one Current Node per branch until the branches reach the group's join.
For example, an SWE workflow can send implementation output to Code Review and QA at the same time, join both results, then continue to an Approval Gate node that decides whether to ship or send the task back for changes.
```text
Implement
|
+--> Code Review --+
| |
+--> QA -----------+--> Join -> | Approval Script | -> Done
```
To create a new parallel group, right-click the node and select "Group". Drag additional agent nodes into the group to add branches.
Wire the group as one fan-out transition from the upstream source to every grouped branch. Each branch then routes to the group's Join node, and the Join routes to the next node in the workflow. When the editor can infer this topology, it creates or preserves the fan-out and join wiring for you.
Joins wait for all required branches. Use the Join to aggregate branch parameters, then put synthesis, release-note writing, approval, or final decision-making in a normal agent/script node after the join.
## 4. Configure Agent Work
### Prompts
Agent prompts live on transitions into agent nodes. The transition prompt is the work order the target agent receives when that branch starts.
Prompts can use task fields:
```md
Implement {{.TaskShortId}}: {{.TaskTitle}}
Task details:
{{.TaskBody}}
```
And parameter values produced by earlier transitions:
```md
Address these review findings:
{{.Params.findings}}
```
Or the previous transition commentary (default output all agents usually provide when they finish the task):
```md
Source transition notes:
{{.Params.commentary}}
```
To reference a guaranteed earlier transition, qualify the parameter with that transition key:
```md
Use the approved plan:
{{.Params.planning.plan_file_path}}
```
A previous-transition parameter is valid only when every path to the prompt passes through that transition. If a value might not exist because of branching, declare a local parameter on the transition that needs it.
### Script Nodes
Use a Script node when a workflow step should run a deterministic local executable instead of an agent. Script nodes can be used anywhere an agent node can be used in the workflow graph.
In complete graph documents, transitions into Script nodes use `context_mode: "new_session"` and `context_source: {"kind":"immediate_source"}`. These required context fields do not create or select a Session for the Script node.
Set the script path on the script node. **All paths are resolved on the server machine.** Relative paths resolve against the task's execution root.
The node script receiver JSON as stdin:
```json
{
"plan_file": "docs/plan.md",
"_kent": {
"task_id": "task_123",
"node_id": "node_456",
"transition_branch_key": "release_notes"
}
}
```
Top-level properties are incoming workflow parameter values. `_kent` contains only the Task and Node identity, plus `transition_branch_key` when the Current Node belongs to a parallel branch.
Stdout must be the workflow completion JSON. Stderr is diagnostics only. For example:
```json
{
"transition": "done",
"commentary": "Generated release notes.",
"release_notes_path": "docs/release-notes.md"
}
```
If the script exits non-zero, writes invalid completion JSON, omits required parameters, or becomes unavailable, Kent interrupts the Current Node. Resume reruns the script with the same incoming parameter values and the current workflow script path and transition contracts.
### Parameters
Parameters are required string outputs from the source agent. They are how one node hands structured facts to the next branch.
For example, a Review to Needs Changes transition can require:
| Parameter | Description |
| -------------- | --------------------------------------------------------------------------- |
| `findings` | Concrete required implementation changes, including file paths when useful. |
| `verification` | Checks the reviewer ran and the results. |
Declare parameters on the transition whose source agent can produce them. In fan-out transitions, matching parameter keys must have matching descriptions because they represent one shared output contract.
For each transition, the source agent must provide the declared parameters before it can complete that branch. The target agent receives those values where the transition prompt references them with placeholders such as `{{.Params.findings}}`.
### Transition Assignee And Thinking Selection
Each eligible serial Agent or Script transition into an Agent Node can independently enable **Let the previous node choose** for the target Assignee and **Let the previous node select thinking level** for thinking. A disabled selector uses the target Agent Node's configured fallback Assignee or configured thinking; Fan-Out transitions do not support either selector.
Transition-selected effort follows the Session's [Thinking settings](/config/#thinking).
Transition-selected Assignees must be explicitly agent-callable roles. With no eligible role, Assignee selection is unavailable; with one eligible role, Kent applies it automatically and hides the Assignee Parameter; with several eligible roles, the source must provide the selected role as an ordinary required value. Thinking selection similarly hides its value when the applicable model catalog has zero or one supported level; with several finite levels it requires a value, while an open catalog accepts a nonblank custom value after a custom description is authored.
Enabled selectors own Protected Parameters in the transition's ordinary ordered Parameters list. Assignee uses the default key `agent_role`, and thinking uses `thinking_level`; operators may edit each key, description, and order, but cannot delete an enabled Protected Parameter. Disabling a selector or making it inapplicable hides its Protected Parameter while retaining its saved settings, and separate incoming transitions keep independent selector state.
### Context Modes
Context mode controls how the target agent starts its session.
It applies to transitions into agent nodes; transitions into joins or terminal nodes do not start agent sessions.
| Mode | Best for | Trade-offs |
| ---------------------------- | -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| New session | Independent work, QA, code review, security review, release note drafting. | Lowest starting context and cleanest role boundary. The prompt and parameters must contain the context the target needs. |
| Compact and continue session | A large phase handing off to another role or another direction. | Adds a handoff step and starts a new session from a summary. Good when full conversation history is unnecessary but a clean summary matters. |
| Continue session | Tight loops and direct follow-up work with retained context. | Preserves conversation history and prompt-cache continuity. Retained target Sessions preserve their Assignee; a target-owned previous-session-or-new transition can select an Assignee when it creates a new Session. |
Continuation modes also have a context source:
- Immediate source uses the session from the node that just completed.
- Selected node uses a previous node that is guaranteed to have run before this transition.
- Previous target uses the latest retained Session associated with this edge's target node. Use it for loops where the workflow returns to a node and should continue that node's prior Session.
- Previous target, or new session uses the latest retained Session associated with this edge's target node when one exists. Use it for re-review loops where the first pass starts fresh and later passes continue the target's prior Session.
Use `new_session` or `compact_and_continue_session` when a transition should establish its selected Assignee and thinking at a fresh Session boundary. Continue Session exposes Assignee selection only when **Previous session from this target, or new session** resolves to a new Session; retained target Sessions preserve their materialized Assignee, while eligible transitions may change thinking without rotating cache lineage.
### Human Approval
A transition can require approval. When the source agent chooses that transition, the task waits before target branches start. Use approvals for plan acceptance, destructive operations, release steps, or any point where you want to inspect the agent's proposed direction. For fan-out transitions, approval gates the whole selected transition before any branch starts.
### Completion Modes
Completion mode controls how an agent node reports that it has finished and which transition it selected.
Only agent nodes have completion modes; Start, Join, and Terminal nodes do not execute agent loops.
| Mode | Use | Cache and cost notes |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Inherit global default | Use the workflow completion mode from [configuration](../config/#workflow). | Same behavior as the resolved configured mode. |
| Auto | Best default for most nodes. Kent picks the effective mode from the workflow shape, provider support, and shell availability. | Usually gives the safest cache/cost trade-off automatically. |
| Structured output | Provider-native structured output. Use it when the provider supports strict structured responses and the node is not part of a `continue_session` chain. | Lowest-friction on capable providers, but prevents the Current Node from starting when unsupported and fully invalidates cache on continued sessions. |
| Tool call | Dedicated completion tool. Use it for providers without structured-output support. | Reliable tool-driven completion, but fully invalidates cache on continued sessions. |
| Shell command | Completion through the agent's shell environment. Prefer this for `continue_session` chains. | Requires the shell tool for the target role and gives the agent shell access, but avoids completion-contract cache invalidation. |
| Unstructured output | Best-effort raw JSON final answer. Use only when you need `continue_session` and cannot use shell command. | Most fragile mode. It avoids dynamic completion metadata, but depends on the model following exact final-answer instructions. |
`Auto` chooses unstructured output if the runtime has no shell available; otherwise it chooses shell command when the workflow contains a `continue_session` transition, structured output on capable providers, and tool call as the remaining fallback.
### Cache And Cost Behavior
Workflow design affects prompt-cache continuity and token spend:
- `continue_session` gives the strongest cache continuity because it keeps the retained Session, conversation history, and provider cache; retained target Sessions preserve their Assignee, and a thinking change does not rotate the cache lineage.
- `new_session` starts clean, establishes the transition's selected or fallback Assignee and thinking, and does not invalidate another Session's cache. The prompt and Parameters must carry enough context because the target agent may spend tokens re-orienting in the workspace.
- `compact_and_continue_session` asks the previous agent for a handoff, then starts a fresh Session from that summary with the transition's selected or fallback Assignee and thinking. It frees context, adds handoff cost, and leaves the previous Session cache behind.
The editor shows draft validation and execution validation. Draft validation catches graph-shape problems such as duplicate keys, invalid prompt placeholders, bad parameter contracts, and incomplete node groups. Execution validation catches automation blockers such as missing prompts, missing roles, invalid start shape, unreachable nodes, and non-terminal nodes that cannot reach a terminal node. A workflow can remain linked to a project while execution validation fails: drafts, Backlog tasks, and comments remain available, but task start and manual movement from Backlog into executable work are blocked until every Agent Node fallback role enables `ask_question`.
## 6. Manage Tasks
Graph edits can be blocked when active tasks would be affected. Prefer cleaning the board from in progress task when editing workflows.
Project Tasks spans every workflow linked to the project. Each task belongs to one project and one linked workflow; the project supplies workspaces and execution environment, while the workflow supplies the automation path.
Tasks are grouped by their workflow state:
- **Active** contains tasks that are queued, running, interrupted, active, waiting for a question, or waiting for approval.
- **Backlog** contains tasks that have not started.
- **Done** contains completed tasks.
Task creation follows the project's workflow links:
- With no linked workflows, use **Link Workflow** before creating a task.
- With one linked workflow, **New Task** creates the task in that workflow, whether or not it is the default.
- With multiple linked workflows, **New Task** uses the linked default workflow. If no linked default exists, use **Link Workflow** instead.
Activating a task opens Task Detail. Activating Labels opens the assignment chooser without opening Task Detail.
Choose the source workspace before starting automation. Agents run in the environment where the Kent server runs, so that environment must have the repository, toolchains, credentials, and local files the workflow needs.
A workflow Session may start, interrupt, resume, approve, or manually move another Task. It cannot target its own Task; Kent derives that ownership from the invoking Session.
### Current Work, Sessions, And Activity
Task detail shows the task's Current Nodes, each Agent Current Node's effective Assignee and thinking when present, and retained Session count. `kent task show` reports the same effective fields; non-Agent Current Nodes omit them. A retained Session can outlive the Current Node that used it, so it remains available through the Session picker after the workflow moves on.
Interrupt stops exact live work. Interrupting a Task stops every live Agent Session and Script for that Task; interrupting a Session selects one live Agent Session. Kent waits for the selected work to stop before returning. Resume waits for the prior scope to retire, resolves the latest workflow definition, then resumes the retained Session or current Script.
Restarting Kent leaves saved tasks untouched and does not restart their work. Resume reconciles unfinished execution only when you explicitly request it. Opening or reconnecting the app does not replay notifications for existing interruptions, approvals, or questions.
Delete permanently removes a quiescent Task. Interrupt preserves the task for Resume.
Task Activity is an infinite-scroll stream of durable comments and retained Session creation. It records a Session as `Session started`.
### Project Labels
A project owns a shared catalog of up to 100 reusable labels across its linked workflows. You can create and rename labels from the label chooser; deleting a label removes it from every task in the project.
Assign labels atomically when creating a task or update them immediately from task detail. Board cards show assigned labels as neutral chips and summarize labels that do not fit.
On the board, a named Label row cycles neutral → included → excluded. An included condition requires the Label; an excluded condition requires its absence. `--label-match any` matches when any included or excluded condition is true, while `all` requires every condition. `No labels` remains a binary filter for tasks without assignments and is mutually exclusive with named conditions. The selected filter persists locally for each project and desktop installation across workflows, navigation, and relaunches.
In Desktop, the route-scoped `Unblocked` chip shows Tasks with zero unsatisfied direct dependencies across the board. It combines with the active Labels filter, and its selection resets when you leave or change the board.
Desktop boards sort each column by Updated, Created, Labels, or Short ID. The default is Updated descending; sorting is applied per column after active Labels and Unblocked filters, and Labels follow the Project catalog order.
Project Tasks sort Active, Backlog, and Done together by Updated, Created, Status, Title, Labels, or Short ID. The default is Updated descending, and sort changes apply immediately while the server preserves the selected order.
The CLI manages the same Project catalog with `kent task label create`, `list`, `move`, `rename`, and `delete`. `move` accepts exactly one placement: first, last, before another label, or after another label. `add` and `remove` update a task's memberships atomically; `task create --label` assigns existing labels in the creation transaction. `kent task list` accepts repeatable `--label` included conditions and `--not-label` excluded conditions. Label selectors are literal: canonical UUIDv4 text selects identity, while every other value is trimmed and matched against the complete case-insensitive Unicode name. `--unlabeled` cannot be combined with either selector flag or an explicit match mode.
### CLI Workflow And Task Scope
CLI workflow selectors are bare canonical UUIDv4 values. Copy them from `kent workflow list` or `kent workflow inspect --summary`.
```bash
kent workflow list --project .
workflow_uuid="<uuid-from-workflow-list>"
kent workflow inspect "$workflow_uuid" --summary
```
#### Transition selector controls
Edge creation and updates expose independent target Assignee and thinking selectors. Enabling a selector initializes its Protected Parameter when needed; `--target-assignee-param` and `--target-thinking-param` customize the protected key and description, including an empty description.
```bash
kent workflow edge add "$workflow_uuid" --from review --transition implement --edge-key implement --to implement --context new_session \
--assignee-selection previous_node --target-assignee-param 'agent_role=Role for the next node' \
--thinking-selection previous_node --target-thinking-param 'thinking_level='
kent workflow edge update "$workflow_uuid" <edge-id> --assignee-selection configured --thinking-selection configured
```
Repeatable `--param` and `--clear-params` edit ordinary Parameters only; they retain Protected Parameters and cannot convert or delete them. Node commands continue to edit the required fallback with `--agent`; selector flags belong to Edge commands.
Workflow deletion cascades through the workflow definition, Project links, and Tasks. Run the command without `--confirm` to inspect the impact, then repeat it with `--confirm`; Kent deletes nothing if the impact changes or blockers remain.
```bash
kent workflow delete "$workflow_uuid"
kent workflow delete "$workflow_uuid" --confirm
```
Project-filtered workflow listing returns the default first, followed by project activity and name. Task creation uses an explicit linked `--workflow` when supplied, otherwise the project default, or the lone linked workflow when no default exists. Several links without a default require an explicit selector.
```bash
kent task create --project . --title "Fix flaky tests" --body "Investigate and repair the failure."
kent task create --project . --workflow "$workflow_uuid" --title "Fix flaky tests" --body "Investigate and repair the failure."
```
Task listing is always project-scoped. Omitting `--workflow` lists tasks across every workflow linked to the project; supplying it narrows the result. Project-wide rows include workflow information when multiple workflows match and omit it when exactly one matches. `--column` and `--sort column` require explicit workflow narrowing.
```bash
kent task list --project .
kent task list --project . --workflow "$workflow_uuid" --column review
```
Use `--unblocked` to select Tasks with no unsatisfied direct dependencies or `--blocked` to select Tasks with at least one unsatisfied direct dependency. The flags are mutually exclusive and apply across the selected workflow scope.
```bash
kent task list --project . --unblocked
kent task list --project . --workflow "$workflow_uuid" --blocked
```
Task sorting accepts `created`, `updated`, `status`, `column`, `title`, `labels`, and `short_id` selectors with explicit `asc` or `desc` directions. A command may provide up to seven distinct selectors in one or repeated `--sort` flags.
### Task Dependencies
Task dependencies connect a Blocker Task to a Blocked Task within one Project.
A Task is unblocked when every direct Blocker Task is done; a Task with no direct dependencies is also unblocked.
```bash
kent task dep add --project . --blocker <blocker-task> --blocked <blocked-task>
kent task dep remove --project . --blocker <blocker-task> --blocked <blocked-task>
kent task dep list --project . <task>
kent task dep list --project . <task> --direction blocks
```
Dependency lists include both direct directions unless `--direction blocks` or
`--direction blocked-by` selects one. Add and remove are idempotent; plain
mutation output is `done`, and `--json` returns the typed outcome and both Task
identities.
Starting a Task or moving it into executable work reports unsatisfied direct
Blocker Tasks before execution-target selection. Rerun the same command with
`--ignore-dependencies` to acknowledge that one operation:
```bash
kent task start <task> --ignore-dependencies
kent task move <task> <target-node-id> --ignore-dependencies
```
### Search Tasks
Literal Search matches case-insensitive Task Short ID substrings plus Task titles and bodies. Complete Short IDs and canonical numeric suffixes rank before partial Short ID matches, while `--include-comments` adds Task Comments.
Raw `--fts5` Search remains limited to the public `title`, `body`, and `comment` columns.
```bash
kent task search "retry policy"
kent task search "retry policy" --project . --status backlog,running
```
Run `kent task search --help` for matching modes, filters, result pagination, output contracts, and validation behavior.
### Manually Move A Task
Manual Move evaluates the destination through the workflow server before changing the task. Agent and Script destinations use a usable incoming Transition even when the destination is not connected to the task's Current Node. A single usable Transition is selected automatically; multiple choices require `--transition` with the authored Transition key. Fan-out Transitions move the whole Task-wide parallel group and create every branch.
```bash
kent task move <task> <target-node-id> --transition <transition-key> \
--values-json '{"plan":{"summary":"Approved plan"}}'
kent task move <task> <target-node-id> --values-file ./move-values.json
```
Values use nested Node-key/output-name identity so equal output names from different Nodes remain distinct. Direct Start and Terminal moves omit `--transition` and values. A destination already Current is a successful no-op. Waiting Questions, lifecycle conflicts, unavailable context Sessions, invalid workflows, unsupported destinations, and unusable incoming Transitions are rejected before mutation with a typed reason.
Desktop shows the server's Transition choices and required values, including exposed Assignee and thinking Protected Parameters and resolved values that can be edited. Manual Move applies the same selector rules as automatic completion: hidden zero/one-option or retained-Session values are omitted or ignored, and supplied values are validated before the target is created. When Execution Target selection is required, the Manual Move dialog closes before that selection; canceling or failing target selection leaves live work unchanged. After target selection succeeds, confirming a move interrupts live Agent and Script work across the task's current parallel group, then applies the selected serial or fan-out Transition. If interruption succeeds but final workflow revalidation fails, the task remains interrupted and the move error is reported.
### Complete Work From The CLI
An Agent completing its own workflow Session runs `kent task complete` with its transition result. Kent resolves that completion through the Session identity plus the `KENT_RUN_ID` and `KENT_STEP_ID` values supplied to the active Agent Step. Missing or stale execution identity rejects completion without changing the Workflow.
Human-forced completion requires exactly one selector: a Session, or a Task with one unambiguous idle executable Current Node.
```bash
kent task complete --force --session <session-id> --transition done
kent task complete --force --task <task-id-or-short-id> --project . --transition done
```
Completion has no Current Node selector. Use `--json` or `--json-file` to submit a JSON transition result instead of individual completion fields.
### Choose The Execution Target
The workflow's execution-target policy chooses where executable agent and script nodes run:
| Policy | Execution root |
| ------------------------- | -------------------------------------------------------------------------------------------------- |
| Ask when execution starts | Select one of the four concrete targets when an unlocked task first reaches executable work. |
| No managed worktree | The task's source workspace. This supports non-Git workspaces and tracks source-workspace changes. |
| Source HEAD | A managed task worktree created from the source repository's current commit. |
| Repository default branch | A managed task worktree created from the default branch configured by local remote-HEAD metadata. |
| Custom Git revision | A managed task worktree created from any branch, tag, or commit that resolves to a commit. |
New workflows ask when execution starts. Kent Desktop offers all four concrete targets when selection is required, preselects the repository default branch, and uses the same dialog when a configured Git target cannot be resolved.
Target selection occurs on the first executable start, manual move, or approval. The task locks the selected mode and managed requested/resolved commit facts only when that initiating action succeeds. Later workflow nodes reuse the locked target; a locked target cannot be replaced with another mode.
Configure a workflow policy or select a concrete target when starting, approving, or manually moving a task:
```bash
kent workflow update <uuid> --execution-target ask-on-first-execution
kent workflow update <uuid> --execution-target none|head|default-branch|ref:<revision>
kent task start <task> --execution-target none|head|default-branch|ref:<revision>
kent task approve <transition-id> --execution-target none|head|default-branch|ref:<revision>
kent task move <task> <target-node-id> --execution-target none|head|default-branch|ref:<revision>
```
These task actions never prompt. Their override applies only to an unlocked task and does not edit the workflow. If selection is required, rerun the same action with one concrete selector. `kent task show` reports the source workspace and, after lock, the durable target mode, requested revision, resolved revision, resolved commit, and recorded managed-worktree path when present. It also reports every exact current session and script target. Task detail does not perform live Git branch discovery; inspect the worktree when branch identity is needed.
More about worktrees on the [Worktree](../worktrees/) page.
# Worktrees
> Create, enter, and delete Git worktrees from Kent.
Kent can create and manage worktrees for you. Agents will enter new worktrees if they need to, and workflows can automatically create worktrees for their tasks (see [workflows](../workflows)). If you want to manually manage worktrees, run `/wt` in the TUI, or ask the agent to use the CLI:
```bash
kent worktree status
kent worktree list
kent worktree create <branch-or-ref> [path]
kent worktree enter <selector>
kent worktree leave
kent worktree delete <selector>
```
Every command supports `--json`. Session-scoped commands automatically use the current Session inside a Kent shell or accept `--session <id>` explicitly.
## Select a Project or Workspace
`list`, `create`, and `delete` work without a Session. Use `--project <project-id>` for that Project's default Workspace, or add `--workspace <workspace-id>` to choose another Workspace within it.
```bash
kent worktree create --project <project-id> --workspace <workspace-id> feature/search
```
Without `--project`, Kent uses the agent's Session, otherwise `--session`, otherwise the current directory. `--workspace` alone selects within that Project. These management commands do not move the Session.
## Select
Select a worktree by its exact ID, branch, display name, or path. IDs take precedence, followed by branch, display name, and path. Ambiguous selectors fail.
`list` labels worktrees by availability:
- **registered**: available to Git and managed by Kent
- **external**: available to Git but not managed by Kent; entering it registers it
- **missing**: managed by Kent, but absent from Git
`list` marks the Session's current worktree with `*` unless `--project` or `--workspace` is supplied. Lists without a Session are markerless.
`status` reports a missing checkout or branch without changing the session's worktree.
## Create and enter
`create` prepares the checkout and runs its setup script. With a Session, the CLI prints a separate `kent worktree enter` command; the TUI enters the worktree after creation succeeds.
`enter`, `leave`, and deletion of the active worktree may finish after the command returns. For an active Session, `enter` and `leave` join Pending Work until the next eligible Agent Step boundary; the Session keeps its current worktree until the change starts. Kent presents these queued actions as `/wt switch <selector>` and `/wt leave`, regardless of whether they came from the TUI or CLI. `--json` returns the operation acknowledgement. Kent reports completion or failure in session activity. A server restart cancels a pending change.
## Delete
The Main Workspace and Git main worktree cannot be deleted. Deletion blocks while another session has active work in the worktree or a background process uses it. Idle sessions using the worktree move to the main workspace before removal.
Dirty worktrees, or worktrees whose state cannot be determined, require `--force`. This flag applies only to the worktree folder. Agent-shell deletion always retains branches; other CLI callers can pass `--delete-branch` to delete a branch only when Git considers it safe. `--force-delete-branch` requires `--delete-branch` and deletes the branch without Git's merged-branch check.
If Git retains the branch, deletion succeeds and the CLI prints `Kept branch <name>: <diagnostic>`.
## Configuration
Use a setup script to prepare new worktrees with local data such as `.env` files, encryption credentials, Gradle wrappers, installed dependencies, local skills, docs, or config.
```toml
[worktrees]
base_dir = "~/.kent/worktrees"
# setup_script = "scripts/setup-worktree.sh"
# setup_timeout_seconds = 60
```
- `base_dir` sets the namespace for Kent-managed worktrees. Automatic and explicit worktree paths must remain inside this directory and must not overlap the source workspace in either direction.
- A persisted managed worktree outside this namespace cannot be activated or restored automatically; move it into the namespace before retrying.
- `setup_script` runs after Kent creates a worktree and before the create command or a workflow run uses it. Relative paths resolve from the source workspace root.
- `setup_timeout_seconds` sets the setup script timeout. The default is `60`; `0` or a negative value disables the timeout.
Kent waits for setup to finish. If setup fails, times out, or is canceled, creation fails and the worktree remains available for inspection, repair, or deletion.
Kent invokes the script with the new worktree as its cwd and three positional arguments:
1. source workspace root
2. branch name
3. worktree root
Kent supplies these reserved environment variables, replacing conflicting inherited values:
- `KENT_WORKTREE_SOURCE_WORKSPACE_ROOT` - Original/main workspace root that created the worktree, e.g. `/home/user/dev/app` or `C:\Users\user\dev\app`.
- `KENT_WORKTREE_BRANCH_NAME` - Branch/ref name selected for the new worktree, e.g. `feature/search-fix`.
- `KENT_WORKTREE_ROOT` - Opaque filesystem path to the newly created worktree; setup script runs with this as cwd, for example `/home/user/.kent/worktrees/app/417`. Use this value instead of deriving a path from the branch name.
- `KENT_WORKTREE_SESSION_ID` - Kent session id that requested the worktree, e.g. `b31234ab-78ce-43d1-8f4c-2d6c6d4adbc1`. Present only when a session initiates creation; Sessionless CLI creation and workflow task setup omit it.
- `KENT_WORKTREE_PROJECT_ID` - Kent project id for the workspace/project, e.g. `project-94b18685-19ed-4513-96bb-bcffa10410ff`.
- `KENT_WORKTREE_WORKSPACE_ID` - Kent workspace binding id for the source workspace, e.g. `workspace-2f7b6d4a`.
- `KENT_WORKTREE_WORKTREE_ID` - UUID for the created worktree, e.g. `c4aaf0cf-4c50-4560-b6a2-6c294d0b1495`.
- `KENT_WORKTREE_CREATED_BRANCH` - Whether Kent created a new branch for this worktree, e.g. `true` or `false`.
- `KENT_WORKTREE_PAYLOAD_JSON` - Full setup payload as one JSON string containing all fields above, e.g. `{"source_workspace_root":"/repo","branch_name":"feature/x","worktree_root":"/repo-wt","session_id":null,"project_id":"...","workspace_id":"...","worktree_id":"...","created_branch":true}`.
It also receives the same payload as JSON on stdin:
```json
{
"source_workspace_root": "/path/to/main/workspace",
"branch_name": "feature/name",
"worktree_root": "/path/to/new/worktree",
"session_id": null,
"project_id": "...",
"workspace_id": "...",
"worktree_id": "...",
"created_branch": true
}
```
`session_id` is nullable: Sessionless CLI creation and workflow task setup supply `null`, while session-originated creation supplies the requesting session ID.