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

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

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:

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

Config is optional. To publish a project override:

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

Kompass ships a bundled base config, then applies the first matching consumer-project override in this order: .opencode/kompass.jsonc, .opencode/kompass.json, kompass.jsonc, kompass.json.

How To Use

OpenCode

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

install the plugin in your OpenCode config
optionally add one project override file to customize commands, agents, tools, skills, and defaults; .opencode/kompass.jsonc is preferred
bundled Kompass skills are registered automatically when the plugin loads, so users do not need to copy skill files manually
use commands like /ask, /review, /pr/create, or /ticket/plan inside OpenCode
for CLI session debugging, use opencode session list to find a session id and opencode export <sessionID> 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

`worker`

Handles generic implementation work and can ask targeted follow-up questions when execution is blocked.

`navigator`

Coordinates structured multi-step workflows by keeping orchestration local and delegating only 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

`/ask`

Answers questions about the current project or codebase.

Details

Usage: /ask <question>

Loads only the relevant repository context needed to answer a project or code question directly.

`/commit`

Stages and commits changes with a generated message.

Details

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.

Details

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.

Details

Usage: /dev <description>

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.

Details

Usage: /learn <what-to-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.

Details

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.

Details

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.

Details

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.

Details

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.

Details

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.

Details

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.

Details

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.

Details

Usage: /rmslop

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

`/ticket/create`

Creates a GitHub issue from a description.

Details

Usage: /ticket/create <description>

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

`/ticket/ask`

Answers a question on a ticket and posts the response.

Details

Usage: /ticket/ask <ticket-reference> <question>

Loads the ticket plus all comments, answers the question using ticket and repository context, and posts the response back to the same ticket.

`/ticket/dev`

Implements a ticket with planning and execution.

Details

Usage: /ticket/dev <ticket-reference>

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.

Details

Usage: /ticket/plan <ticket-reference>

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

Tools

`changes_load`

Load branch changes against a base branch.

Details

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.

Details

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.

Details

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
head (optional): head branch to use when creating a PR
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.

Details

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.

Details

Parameters:

title (optional): issue title; required when creating a new issue or renaming one
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
comments (optional): issue comments to post without replacing the issue body

Why it helps:

lets ticket flows create a new issue, update an existing one, or post a ticket comment with one tool
avoids making the agent handcraft raw gh issue commands each time

`reload`

Refresh the OpenCode project cache.

Details

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 project override locations in precedence order:

.opencode/kompass.jsonc
.opencode/kompass.json
kompass.jsonc
kompass.json

See kompass.jsonc for the published base config, .opencode/kompass.jsonc for the preferred consumer-project override shape, 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:

{ "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

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

Name		Name	Last commit message	Last commit date
Latest commit History 201 Commits
.agent/skills		.agent/skills
.agents/skills/frontend-skill		.agents/skills/frontend-skill
.github		.github
.opencode		.opencode
assets		assets
packages		packages
.gitignore		.gitignore
AGENTS.md		AGENTS.md
LICENSE		LICENSE
README.md		README.md
TODO.md		TODO.md
bun.lock		bun.lock
kompass.jsonc		kompass.jsonc
kompass.schema.json		kompass.schema.json
package.json		package.json
skills-lock.json		skills-lock.json
tsconfig.json		tsconfig.json

Folders and files

Latest commit

History

Repository files navigation

Choose Your Mode

Why Kompass?

Installation

How To Use

OpenCode

Claude Code

Agents

worker

navigator

planner

reviewer

Commands

/ask

/commit

/commit-and-push

/dev

/learn

/pr/create

/pr/fix

/pr/review

/reload

/review

/ship

/todo

/rmslop

/ticket/create

/ticket/ask

/ticket/dev

/ticket/plan

Tools

changes_load

pr_load

pr_sync

ticket_load

ticket_sync

reload

Config

Workspace

Workspace Scripts

Publishing Direction

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases 14

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`worker`

`navigator`

`planner`

`reviewer`

`/ask`

`/commit`

`/commit-and-push`

`/dev`

`/learn`

`/pr/create`

`/pr/fix`

`/pr/review`

`/reload`

`/review`

`/ship`

`/todo`

`/rmslop`

`/ticket/create`

`/ticket/ask`

`/ticket/dev`

`/ticket/plan`

`changes_load`

`pr_load`

`pr_sync`

`ticket_load`

`ticket_sync`

`reload`

Packages