Kenn Forge

https://forge.kenn.io/docs
Admin
Kenn Forge is a local console for repository activity, pull requests, issues, reviews, and agent...
Tokens:18,710
Snippets:208
Trust Score:6.4
Update:1 month ago
Show doc for...
Tokens:
Raw
### Start Forge daemon with GitHub CLI

Source: https://forge.kenn.io/docs/quickstart

Authenticates the GitHub CLI and starts the Forge daemon. Assumes kenn-forge is on PATH; after make build use ./kenn-forge instead or run make install. Open http://127.0.0.1:8091 after starting.

```sh
gh auth login
kenn-forge daemon start
```

--------------------------------

### Start with alternate config using kenn-forge serve --config

Source: https://forge.kenn.io/docs/troubleshooting

Start Kenn Forge with an alternative configuration file to avoid a busy port. Use the --config flag to point to a different config.toml.

```sh
kenn-forge serve --config /path/to/config.toml
```

--------------------------------

### Create, install, and list a GitHub App

Source: https://forge.kenn.io/docs/configuration

Use the companion CLI to keep sync reads off your personal rate limit. The CLI writes [[github_apps]] entries. Mutations still use a user PAT. After changing selected repository access on GitHub, run install again and restart Forge.

```sh
kenn-forge-github-app create
kenn-forge-github-app install
kenn-forge-github-app list
```

--------------------------------

### Create and install an archive GitHub App

Source: https://forge.kenn.io/docs/configuration

Create a second GitHub App with its own installation budget for a busy historical archive. The archive App must be installed on the same repository account and must be a distinct GitHub App. Archive reads use it only for repositories it covers; ordinary sync and mutations keep using the normal App/PAT routes.

```sh
kenn-forge-github-app create --role archive
kenn-forge-github-app install --app-id <archive-app-id>
```

--------------------------------

### Build Forge from source with make build

Source: https://forge.kenn.io/docs/quickstart

Clones the Forge repository and builds it from source. Requires Go 1.27+ and Bun. The build embeds the frontend in ./kenn-forge; run make install to install an optimized binary.

```sh
git clone https://github.com/kenn-io/forge.git kenn-forge
cd kenn-forge
make build
```

--------------------------------

### Get help for kenn-forge pulls and sync

Source: https://forge.kenn.io/docs/commands

Get help for the data query and sync commands. The CLI includes commands for `activity`, `issues`, `pulls`, `repos`, `repo-summaries`, `stacks`, `workspaces`, `rate-limits`, and `sync`. Use the command help before scripting an output shape.

```sh
kenn-forge pulls --help
kenn-forge sync --help
```

--------------------------------

### Set GitHub token and start daemon

Source: https://forge.kenn.io/docs/quickstart

Set the GitHub token environment variable and start the daemon. Use when the GitHub CLI is unavailable or when connecting another provider or host. The token is read from the environment variable; settings does not store credentials.

```sh
export KENN_FORGE_GITHUB_TOKEN=ghp_your_token_here
kenn-forge daemon start
```

```powershell
$env:KENN_FORGE_GITHUB_TOKEN = 'ghp_your_token_here'
kenn-forge.exe daemon start
```

--------------------------------

### Start archive for a repository or all repositories

Source: https://forge.kenn.io/docs/archive

Promote one repository or all repositories to full archival. Discovery mode records item identities without loading every detail. Progress survives daemon restarts and repositories advance independently.

```sh
kenn-forge archive start --repo 'github|github.com/owner/repo'
kenn-forge archive start --all

```

--------------------------------

### Manage GitHub App credentials with kenn-forge-github-app

Source: https://forge.kenn.io/docs/commands

Manage GitHub App credentials. Use this companion CLI when sync or archive reads should use GitHub App installation tokens. `--role archive` creates a separate installation route for historical archive work. Comments, reviews, state changes, and merges still use the user PAT chain.

```sh
kenn-forge-github-app create
kenn-forge-github-app create --role archive
kenn-forge-github-app list
kenn-forge-github-app install
kenn-forge-github-app uninstall
kenn-forge-github-app delete
kenn-forge-github-app open
```

--------------------------------

### Install agent activity hooks with kenn-forge agent-hook

Source: https://forge.kenn.io/docs/commands

Install or remove agent activity hooks. Without `--agent`, install or remove every supported integration. Installed hooks send lifecycle activity to the running daemon. Codex asks you to review the installed commands through `/hooks` once.

```sh
kenn-forge agent-hook install
kenn-forge agent-hook install --agent codex
kenn-forge agent-hook uninstall
kenn-forge agent-hook uninstall --agent codex
```

--------------------------------

### Install agent lifecycle hooks with kenn-forge agent-hook install

Source: https://forge.kenn.io/docs/workflows

Install lifecycle hooks to show agent activity in workspace rows. Use --agent NAME to limit installation to a specific agent. Hook reports expire after 30 minutes without another event, then fall back to tmux activity.

```sh
kenn-forge agent-hook install
```

--------------------------------

### Check Kata daemon config at ~/.kata/config.toml

Source: https://forge.kenn.io/docs/troubleshooting

Check Kata's own configuration file for daemon definitions. Forge does not store Kata daemon definitions, so this file is the source of truth. Set KATA_HOME before starting Forge if the config is elsewhere.

```text
~/.kata/config.toml
```

--------------------------------

### Run kenn-forge serve in foreground

Source: https://forge.kenn.io/docs/commands

Run the daemon in the foreground for development or diagnosis. Foreground starts reject a second process using the same data directory.

```sh
kenn-forge serve
kenn-forge serve --config /path/to/config.toml
```

--------------------------------

### Configure app modes in TOML

Source: https://forge.kenn.io/docs/configuration

Sets which top-level pages are visible. Set a mode to false to hide it; docs starts hidden because it needs configured local folders. Kata integration is contextual rather than a top-level mode.

```toml
[modes]
activity = true
repos = true
docs = false
pulls = true
issues = true
reviews = true
workspaces = true
```

--------------------------------

### Manage the kenn-forge daemon

Source: https://forge.kenn.io/docs/commands

Manage the kenn-forge daemon. `daemon start` and `daemon stop` are idempotent; start returns after the daemon publishes its ready identity and safely reuses a compatible running process. Use `daemon restart` after changing startup configuration or replacing the binary. On Unix, stop sends SIGTERM once; if the daemon does not exit within 15 seconds, the command leaves it running and directs you to inspect and terminate it manually.

```sh
kenn-forge daemon start
kenn-forge daemon status
kenn-forge daemon status --json
kenn-forge daemon restart
kenn-forge daemon stop
```

--------------------------------

### Configure MCP client with HTTP URL and optional bearer token

Source: https://forge.kenn.io/docs/kenn-forge-mcp

Configure an MCP client with the HTTP URL. The first example is for when API authentication is disabled; the second adds an Authorization header with a bearer token when [api].require_auth is enabled. The token is read from the auth_token file in the daemon's data directory (mode 0600), not pasted into shared configuration.

```json
{
  "mcpServers": {
    "kenn-forge": {
      "type": "http",
      "url": "http://127.0.0.1:8092/mcp"
    }
  }
}
```

```json
{
  "mcpServers": {
    "kenn-forge": {
      "type": "http",
      "url": "http://127.0.0.1:8092/mcp",
      "headers": {
        "Authorization": "Bearer ${KENN_FORGE_API_TOKEN}"
      }
    }
  }
}
```

--------------------------------

### Check daemon status with kenn-forge daemon status

Source: https://forge.kenn.io/docs/troubleshooting

Check whether the Kenn Forge daemon is running and see the startup banner. If another process uses the same data_dir, the banner shows the existing daemon's URL; use that URL instead of starting a second daemon.

```sh
kenn-forge daemon status
```

--------------------------------

### Generate archive report with date range and verbose output

Source: https://forge.kenn.io/docs/archive

Generate reports using UTC. --days selects rolling 24-hour periods; date-only ranges include both dates; RFC3339 ranges use inclusive start and exclusive end. Markdown is default; use --format json, --output PATH, and repeated --repo filters for automation.

```sh
kenn-forge archive report --days 7
kenn-forge archive report --start 2026-07-01 --end 2026-07-07 --verbose

```

--------------------------------

### Add or override a workspace agent in TOML

Source: https://forge.kenn.io/docs/configuration

Adds or overrides a workspace agent that Forge detects on PATH. The example defines an agent with key review, label Review Agent, and command review-agent --fast. Agents can also be edited under Settings → Agents.

```toml
[[agents]]
key = "review"
label = "Review Agent"
command = ["review-agent", "--fast"]
```

--------------------------------

### Disable telemetry with TELEMETRY_ENABLED=0

Source: https://forge.kenn.io/docs/configuration

Disable anonymous telemetry when starting the daemon. Telemetry is enabled by default and includes daemon activity, app view names, version, commit, OS, architecture, and an anonymous install ID. It does not send repository names, item content, tokens, usernames, hostnames, or paths.

```sh
TELEMETRY_ENABLED=0 kenn-forge daemon start
```

--------------------------------

### Configure server and storage in config.toml

Source: https://forge.kenn.io/docs/configuration

Set server and storage options: `sync_interval` controls provider refreshes, `host` and `port` set the listener, `base_path` adds a URL prefix behind a reverse proxy, and `data_dir` moves app data while leaving config under `KENN_FORGE_HOME`.

```toml
sync_interval = "5m"
host = "127.0.0.1"
port = 8091
base_path = "/"
```

--------------------------------

### Configure provider and host credentials in TOML

Source: https://forge.kenn.io/docs/configuration

Shows how to configure credentials in TOML, scoped by provider and host. An exact repository token_file or token_env takes priority over broader credentials; empty files and variables are skipped. Token files are read on each request, so replacing a file atomically rotates that credential.

```toml
github_token_env = "KENN_FORGE_GITHUB_TOKEN"

[[platforms]]
type = "forgejo"
host = "forge.example.com"
token_env = "FORGE_EXAMPLE_TOKEN"

[[repos]]
platform = "forgejo"
platform_host = "forge.example.com"
owner = "team"
name = "private-service"
token_file = "~/.kenn/forge/tokens/private-service"
```

--------------------------------

### Pause archive for all repositories or a specific repository

Source: https://forge.kenn.io/docs/archive

Pause stops new archive work without deleting data. Start and pause are idempotent; starting the same scope resumes durable progress. There is no manual cursor reset.

```sh
kenn-forge archive pause --all
kenn-forge archive pause --repo 'github|github.com/owner/repo'

```

--------------------------------

### Configure docs folder with [[doc_folders]]

Source: https://forge.kenn.io/docs/configuration

Equivalent configuration for a docs folder. The `daemon` field is optional; set it when task links in this folder always belong to one Kata daemon.

```toml
[[doc_folders]]
id = "notes"
name = "Notes"
path = "/Users/you/notes"
daemon = "kata-main"
```

--------------------------------

### Enable Docs mode and register a Markdown folder

Source: https://forge.kenn.io/docs/quickstart

Enable the Docs mode by setting docs = true in the [modes] section of the configuration. Then register a local Markdown folder with the kenn-forge docs add-folder command, specifying a name and the folder path.

```toml
[modes]
docs = true
```

```sh
kenn-forge docs add-folder --name Notes ~/notes
```

--------------------------------

### Configure reverse proxy and SSE buffer in config.toml

Source: https://forge.kenn.io/docs/configuration

Configure a trusted reverse proxy or a larger SSE replay window. `allowed_hosts` accepts exact host and port values; a trusted proxy must present accepted direct and forwarded hosts. `sse_buffer_size` defaults to 256 and accepts 16 through 16384.

```toml
allowed_hosts = ["forge.example.com", "proxy.example.com:8091"]
trust_reverse_proxy = true
sse_buffer_size = 256
```

--------------------------------

### Check Roborev status with curl

Source: https://forge.kenn.io/docs/troubleshooting

Check the Roborev daemon status endpoint. Use when Forge does not start Roborev and you need to confirm the daemon is running.

```sh
curl http://127.0.0.1:7373/api/status
```

--------------------------------

### Enable MCP companion in config.toml and restart daemon

Source: https://forge.kenn.io/docs/kenn-forge-mcp

Enable the MCP companion by adding the [mcp] section to ~/.kenn/forge/config.toml, then restart the daemon. The port setting is optional and defaults to the main backend port plus one.

```toml
[mcp]
enabled = true
# port = 8092 # defaults to the main backend port plus one
```

```sh
kenn-forge daemon restart
```

--------------------------------

### Restart daemon with kenn-forge daemon restart

Source: https://forge.kenn.io/docs/troubleshooting

Restart the daemon after editing config.toml because most configuration loads at startup. For isolated test state, set KENN_FORGE_HOME before starting Forge.

```sh
kenn-forge daemon restart
```

--------------------------------

### Configure the hub with fleet, peers, and API authentication

Source: https://forge.kenn.io/docs/federated-fleet

Configure the hub for remote federation. Set fleet.enabled to true, provide a unique fleet.key, and optionally set peer_timeout (defaults to 2s). include_unmanaged_details=false limits unmanaged tmux session details. For SSH peers, destination accepts a validated [user@]host, optional port, IPv6 literal, or ssh:// URI; remote_command must be a bare executable name or path without flags or shell syntax. require_auth=true protects the hub API, but HTTP peers must travel over a trusted private network. Restart the hub after changing API authentication or SSH peer entries.

```toml
[fleet]
enabled = true
key = "studio"
peer_timeout = "2s"

[fleet.sessions]
include_unmanaged_details = false

[[fleet.peers]]
key = "desktop"
name = "Desktop"
base_url = "http://desktop.internal.example:8091"

[[fleet.ssh_peers]]
key = "build"
name = "Build host"
destination = "maintainer@build.internal.example"
remote_command = "kenn-forge"

[api]
require_auth = true
```

--------------------------------

### Enable MCP companion in config.toml

Source: https://forge.kenn.io/docs/configuration

Enable the daemon's optional loopback MCP listener. The sessionless Streamable HTTP endpoint is `http://127.0.0.1:<resolved-port>/mcp`; authentication follows `[api].require_auth`. Full diff files use a request-based least-recently-used cache; `diff_cache_mb` defaults to 128 MiB. MCP listener or cache changes require a daemon restart.

```toml
[mcp]
enabled = true
# port = 8092 # defaults to the main backend port plus one
diff_cache_mb = 128
```

--------------------------------

### Configure a GitLab platform and repository with nested namespace

Source: https://forge.kenn.io/docs/configuration

Sets a self-hosted GitLab platform with token_env and a repo that references it via platform and platform_host. repo_path preserves nested namespaces or canonical casing.

```toml
[[platforms]]
type = "gitlab"
host = "gitlab.example.com"
token_env = "GITLAB_EXAMPLE_TOKEN"

[[repos]]
platform = "gitlab"
platform_host = "gitlab.example.com"
owner = "group/subgroup"
name = "project"
repo_path = "group/subgroup/project"
```

--------------------------------

### Configure tmux command in [tmux] section

Source: https://forge.kenn.io/docs/configuration

Configure a different tmux socket or wrap the launch. The command line is used verbatim; wrapper commands run with a minimal non-secret environment, so pass custom data as arguments, not environment variables.

```toml
[tmux]
command = ["tmux", "-L", "kenn-forge"]
```

--------------------------------

### Configure Activity defaults in TOML

Source: https://forge.kenn.io/docs/configuration

Sets the initial Activity view and local default-branch retention. Values include view_mode, time_range, hide_closed, hide_bots, collapse_threads, default_branch_retention_days, and default_branch_max_commits.

```toml
[activity]
view_mode = "threaded"
time_range = "7d"
hide_closed = false
hide_bots = false
collapse_threads = true
default_branch_retention_days = 90
default_branch_max_commits = 5000
```

--------------------------------

### Register a docs folder and enable docs mode

Source: https://forge.kenn.io/docs/troubleshooting

Register a docs folder with the kenn-forge CLI, then enable the docs mode in the Forge configuration. The folder must be registered before the mode can be enabled.

```sh
kenn-forge docs add-folder --name Docs ~/docs
```

```toml
[modes]
docs = true
```

--------------------------------

### Bind a Docs folder to a Kata daemon

Source: https://forge.kenn.io/docs/workflows/docs

Register a folder and bind it to a specific Kata daemon using `--id` and `--daemon` flags. This allows recognized task references to open in Kata.

```sh
kenn-forge docs add-folder --id project --daemon kata-main ~/project-docs
```

--------------------------------

### Map Kata project to repository

Source: https://forge.kenn.io/docs/integrations

Manually map a Kata project to a repository when automatic matching is wrong. The daemon_id is optional; omit it to apply the mapping to every configured daemon.

```toml
[[kata_projects]]
daemon_id = "kata-main"
project_uid = "widgets"
provider = "github"
platform_host = "github.com"
repo_path = "acme/widgets"
```

--------------------------------

### Configure a GitHub repository with owner and name in TOML

Source: https://forge.kenn.io/docs/configuration

Minimal [[repos]] entry for a GitHub repository on github.com; only owner and name are required. A common HTTPS or SSH repository URL can be pasted into either field and Forge normalizes it.

```toml
[[repos]]
owner = "team"
name = "service"
```

--------------------------------

### Map GitHub owner tokens in TOML

Source: https://forge.kenn.io/docs/configuration

Maps fine-grained PATs to GitHub owners when one token cannot read every repository. Owner mappings are configured in TOML only. GitHub selects credentials by host and owner; exact repository credentials win, and owner PATs handle uncovered reads and user-attributed writes.

```toml
[[github_owner_tokens]]
owner = "org-a"
token_env = "KENN_FORGE_GITHUB_TOKEN_ORG_A"

[[github_owner_tokens]]
owner = "org-b"
token_file = "~/.kenn/forge/tokens/org-b"
```

--------------------------------

### Read configuration with kenn-forge config read

Source: https://forge.kenn.io/docs/commands

Read configuration values. Use Settings or edit TOML for normal configuration changes.

```sh
kenn-forge config read port
kenn-forge config read --config /path/to/config.toml port
```

--------------------------------

### Verify checksum on Linux with sha256sum

Source: https://forge.kenn.io/docs/quickstart

Run this command in the directory containing the downloaded archive and SHA256SUMS file. It verifies the archive's checksum and ignores missing files.

```sh
sha256sum -c SHA256SUMS --ignore-missing
```

--------------------------------

### Open authenticated hub with auth_token query parameter

Source: https://forge.kenn.io/docs/federated-fleet

Open an authenticated hub when require_auth=true. Read the hub token from <data_dir>/auth_token (default ~/.kenn/forge/auth_token). Forge exchanges the token for an HttpOnly browser cookie, then redirects to the clean URL. The cookie also authenticates terminal WebSocket requests. Do not share the tokenized URL.

```text
http://127.0.0.1:8091/?auth_token=<token>
```

--------------------------------

### Configure self-hosted Gitea over HTTP with allow_insecure

Source: https://forge.kenn.io/docs/configuration

Defines a Gitea platform on a private deployment using an explicit base_url and allow_insecure = true. host must match Gitea's advertised clone URLs; Forge rejects plain-HTTP or mismatched clone URLs before using them.

```toml
[[platforms]]
type = "gitea"
host = "gitea.example.test:3000"
base_url = "http://gitea.example.test:3000"
allow_insecure = true
token_env = "GITEA_PRIVATE_TOKEN"
```

--------------------------------

### Check kenn-forge build information

Source: https://forge.kenn.io/docs/commands

Check build information. The JSON object contains `name`, `version`, `commit`, and `buildDate`. `buildDate` is a UTC RFC3339 timestamp or `unknown` for an uninjected build. This command does not read config or connect to a daemon.

```sh
kenn-forge version
kenn-forge version --json
```

--------------------------------

### Configure Roborev endpoint and managed clones

Source: https://forge.kenn.io/docs/integrations

Configure the Roborev daemon endpoint and optional managed-clone initialization. The endpoint defaults to http://127.0.0.1:7373; restart Forge after changing it. init_managed_clones is off by default and can be changed live under Settings → Workspaces.

```toml
[roborev]
endpoint = "http://127.0.0.1:7373"
init_managed_clones = true
```

--------------------------------

### Manage Docs folders with kenn-forge docs

Source: https://forge.kenn.io/docs/commands

Manage Docs folders. These commands manage `[[doc_folders]]` in the selected config file.

```sh
kenn-forge docs list-folders
kenn-forge docs add-folder --name Docs ~/docs
kenn-forge docs add-folder --id project --daemon kata-main ~/project-docs
kenn-forge docs remove-folder project
```

--------------------------------

### Verify checksum on macOS with shasum

Source: https://forge.kenn.io/docs/quickstart

Run these commands in the directory containing the downloaded archive and SHA256SUMS file. They compute the SHA-256 hash of the archive and search for its expected checksum in SHA256SUMS.

```sh
shasum -a 256 forge_<version>_darwin_<arch>.tar.gz
grep 'forge_<version>_darwin_<arch>.tar.gz' SHA256SUMS
```

--------------------------------

### Forge database file path

Source: https://forge.kenn.io/docs/troubleshooting

Path to the Forge database file. Use when troubleshooting database migration issues.

```text
~/.kenn/forge/forge.db
```

--------------------------------

### Verify checksum on Windows PowerShell

Source: https://forge.kenn.io/docs/quickstart

Run these commands in PowerShell in the directory containing the downloaded archive and SHA256SUMS file. They compute the SHA-256 hash of the archive and search for its expected checksum in SHA256SUMS.

```powershell
Get-FileHash .\forge_<version>_windows_amd64.zip -Algorithm SHA256
Select-String -Path .\SHA256SUMS -Pattern 'forge_<version>_windows_amd64.zip'
```

--------------------------------

### Test SSH peer destination with ssh -o BatchMode=yes

Source: https://forge.kenn.io/docs/federated-fleet

Use when an SSH peer does not connect. Tests the exact destination from the hub machine with batch mode to avoid password prompts. Confirm kenn-forge is on the remote login PATH and set KENN_FORGE_HOME if the peer uses another home directory.

```sh
ssh -o BatchMode=yes maintainer@build.internal.example true
```
Tokens:
Raw