Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/kompassdev/kompass

Navigate your way - manual steering, steered autonomy, or autonomously. Kompass keeps AI coding agents on course with token-efficient, composable workflows.
https://github.com/kompassdev/kompass

agent-navigation ai automation autonomous-coding code-review coding-agent developer-tools github kompass steered-autonomy token-efficiency workflow

Last synced: 6 days ago
JSON representation

Navigate your way - manual steering, steered autonomy, or autonomously. Kompass keeps AI coding agents on course with token-efficient, composable workflows.

Awesome Lists containing this project

README 

          
> Kompass is under active development, so workflows, package APIs, and adapter support may keep evolving as the toolkit expands.





  Kompass

  


  Navigate your way - manual steering, steered autonomy, or autonomously.




Kompass keeps AI coding agents on course with token-efficient, composable workflows. **Finally, your agent stops wandering.**



Whether you prefer full control, guided collaboration, or hands-off autonomy, Kompass adapts to how you work.



## Choose Your Mode



**🧭 Manual Steering** — You chart the course, the agent follows your lead


**⚓ Collaborative** — Plan together, develop together, review together


**🚢 Autonomous** — Let your agent navigate independently, review at checkpoints



## Why Kompass?



| Challenge | How Kompass Helps |

|-----------|-------------------|

| Agents wander without direction | 🧭 **Navigation** — structured workflows keep agents on course |

| Rebuilding prompts for every agent | 🔌 **Plug & Play** — same workflows across OpenCode, Claude Code, and more |

| Token bloat in long sessions | 🎯 **Token Efficient** — minimal, focused prompts that get to the point |

| Ad-hoc planning and review | ⚓ **Workflows** — purpose-built flows for plan, dev, and review |

| Generic tools miss context | 🛠️ **Tailored Tools** — purpose-built for repository work |

| Complex setup overhead | ⚡ **Easy to Use** — install the plugin, start navigating |



## Installation



For OpenCode, add the adapter package to your config:



```json

{

  "plugin": ["@kompassdev/opencode"]

}

```



Config is optional. To publish a config file:



```bash

# Inside .opencode folder

curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o .opencode/kompass.jsonc



# Project root

curl -fsSL https://raw.githubusercontent.com/kompassdev/kompass/main/kompass.jsonc -o kompass.jsonc

```



Kompass prefers `.opencode/kompass.jsonc`, then `kompass.jsonc`, and still accepts the legacy `.json` filenames.



## How To Use



### OpenCode



Use `@kompassdev/opencode` when you want Kompass workflows inside OpenCode.



- install the plugin in your OpenCode config

- optionally add `.opencode/kompass.jsonc` or `kompass.jsonc` to customize commands, agents, tools, skills, and defaults

- bundled Kompass skills are registered automatically when the plugin loads, so users do not need to copy skill files manually

- use commands like `/review`, `/pr/create`, or `/ticket/plan` inside OpenCode

- for CLI session debugging, use `opencode session list` to find a session id and `opencode export ` to dump the raw session JSON



### Claude Code



Claude Code adapter support is coming soon.



Kompass is being structured as a shared core toolkit with adapter-specific packages, so the same workflows can be reused across agents instead of rebuilt from scratch.



## Agents



### `navigator`



Coordinates multi-step workflows like `/todo` and `/ship` by keeping orchestration local and delegating focused leaf work to subagents.



### `planner`



Turns a request or ticket into a scoped implementation plan.



### `reviewer`



Reviews branch or PR changes without editing files.



## Commands



### `/commit`



Stages and commits changes with a generated message.



**Usage:** `/commit [message]`



If a message is provided, commits with that message. Otherwise, generates an appropriate commit message based on the staged changes.



### `/commit-and-push`



Stages, commits, and pushes changes in one workflow.



**Usage:** `/commit-and-push [message]`



Commits changes (generating a message if not provided) and pushes to the remote repository.



### `/dev`



Implementation mode for focused development work.



**Usage:** `/dev `



Use for active development tasks. The agent implements the described changes while staying focused on the task.



### `/learn`



Learns patterns and conventions from existing code.



**Usage:** `/learn `



Analyzes the codebase to understand patterns, conventions, or specific implementations. Useful for understanding how things work before making changes.



### `/pr/create`



Creates a pull request with structured checklists.



**Usage:** `/pr/create [title]`



Creates a PR from the current branch. Generates a title if not provided. Includes checklist sections for consistent PR structure.



### `/pr/fix`



Fixes issues found during PR review.



**Usage:** `/pr/fix [context]`



Addresses review comments and feedback on an open PR. Loads the PR context and works through requested changes.



### `/pr/review`



Reviews a pull request and adds structured feedback.



**Usage:** `/pr/review [pr]`



Reviews the specified PR (or current PR if not specified) and provides feedback using inline comments and review threads.



### `/reload`



Reloads the OpenCode project cache.



**Usage:** `/reload`



Refreshes config, commands, agents, and tools without restarting OpenCode. Useful after making changes to `kompass.jsonc`.



### `/review`



Reviews branch changes for issues and improvements.



**Usage:** `/review [base]`



Reviews uncommitted changes or changes against a base branch (default: main). Provides feedback on code quality, patterns, and potential issues.



### `/ship`



Ships the fast path from change summary to commit and PR creation.



**Usage:** `/ship [base-or-context]`



Summarizes current changes, creates a feature branch when you are still on the base branch, then delegates the commit and PR steps to `/commit` and `/pr/create`.



### `/todo`



Works through a todo file task by task.



**Usage:** `/todo [todo-file]`



Loads a todo list, delegates one item at a time, and keeps orchestration local so work can pause and resume cleanly.



### `/rmslop`



Removes unnecessary code and simplifies.



**Usage:** `/rmslop`



Analyzes the codebase for unnecessary complexity, unused code, and opportunities for simplification.



### `/ticket/create`



Creates a GitHub issue from a description.



**Usage:** `/ticket/create `



Creates a new GitHub issue with the provided description, generating a title and structured body with checklists.



### `/ticket/dev`



Implements a ticket with planning and execution.



**Usage:** `/ticket/dev `



Loads the specified ticket (URL, #id, or file path), creates an implementation plan, and executes the work.



### `/ticket/plan`



Creates an implementation plan for a ticket.



**Usage:** `/ticket/plan `



Loads the specified ticket and creates a detailed implementation plan without executing changes.



## Tools



### `changes_load`



Load branch changes against a base branch.



**Parameters:**



- `base` (optional): base branch or ref

- `head` (optional): head branch, commit, or ref override

- `depthHint` (optional): shallow-fetch hint such as PR commit count

- `uncommitted` (optional): only load uncommitted changes (staged and unstaged), never fall back to branch comparison



**Why it helps:**



- keeps branch diff loading focused

- works well for review and PR workflows

- handles workspace changes separately from committed branch diffs



### `pr_load`



Load PR metadata and review history.



**Parameters:**



- `pr` (optional): PR number or URL



**Why it helps:**



- gives agents normalized PR context before they start reviewing or summarizing

- keeps review workflows grounded in actual PR state instead of inferred context



### `pr_sync`



Create, update, or review a GitHub pull request with structured checklists.



**Parameters:**



- `title` (optional): PR title; required when creating a PR or renaming one

- `body` (optional): raw PR body override

- `description` (optional): short PR description rendered above checklist sections

- `base` (optional): base branch to merge into

- `checklists` (optional): structured checklist sections (e.g., Testing, Summary)

- `draft` (optional): create as draft PR

- `refUrl` (optional): PR URL to update instead of creating new

- `commitId` (optional): commit SHA to anchor review comments to

- `review` (optional): structured review submission with optional `body`, inline `comments`, and `approve` flag

- `replies` (optional): replies to existing review comments

- `commentBody` (optional): general PR comment body



**Why it helps:**



- consistent PR creation with checklist support

- create, update, review, approve, and reply with one tool

- no shell escaping issues



### `ticket_load`



Load a ticket from GitHub, file, or text.



**Parameters:**



- `source` (required): issue URL, repo#id, #id, file path, or raw text

- `comments` (optional): include issue comments



**Why it helps:**



- lets the same workflow start from GitHub, a local file, or pasted text

- gives planning and implementation flows a consistent input format



### `ticket_sync`



Create or update a GitHub issue with checklists.



**Parameters:**



- `title` (required): issue title

- `body` (optional): raw issue body override

- `description` (optional): short issue description rendered above checklist sections

- `labels` (optional): labels to apply when creating or updating the issue

- `checklists` (optional): structured checklist sections rendered as markdown

- `refUrl` (optional): issue URL to update instead of creating a new issue



**Why it helps:**



- lets ticket flows create a new issue or update an existing one with one tool

- avoids making the agent handcraft raw `gh` issue commands each time



### `reload`



Refresh the OpenCode project cache.



**Parameters:** none



**Why it helps:**



- refresh config, commands, and tools without restarting

- useful after making changes to `kompass.jsonc`



## Config



Project config is optional.



If you want to customize Kompass, use one of these preferred locations in the consumer project:



- `.opencode/kompass.jsonc`

- `kompass.jsonc`



See `kompass.jsonc` for the root example, `packages/opencode/.opencode/kompass.jsonc` for the compiled OpenCode-scoped example, and `kompass.schema.json` for the schema.



Tool names can also be remapped per adapter. For example, this keeps `ticket_sync` enabled but exposes it as `custom_ticket_name`, and Kompass command or agent references are rewritten to match:



```jsonc

{

  "tools": {

    "ticket_sync": {

      "enabled": true,

      "name": "custom_ticket_name"

    }

  }

}

```



## Workspace



This repository is the Kompass development workspace.



- `packages/core`: shared Kompass workflows, prompts, components, config loading, and tool definitions

- `packages/opencode`: the OpenCode adapter package, published as `@kompassdev/opencode`



The root coordinates workspace scripts, shared config, tests, and compiled review output.



## Workspace Scripts



```bash

bun run compile

bun run typecheck

bun run test

```



`bun run compile` regenerates `packages/opencode/.opencode/` from the OpenCode package.



## Publishing Direction



- publish `packages/opencode` as `@kompassdev/opencode`

- keep shared workflow logic in `packages/core`

- add future adapters as sibling packages, such as `packages/claude-code`