Koji

Obsidian-powered CLI for task tracking, research vaults, and knowledge management. Markdown files with YAML frontmatter, Dataview queries, and a fast CLI for all mutations.

What Is This?

Koji manages structured vaults of markdown files. Each vault has tasks, epics, sprints, knowledge entries, and domain definitions — all stored as markdown with YAML frontmatter. Works standalone in any terminal, and doubles as an Obsidian vault with live Dataview dashboards.

Different presets adapt koji to different use cases:

Preset	Use Case	Statuses	Entry Types
tracker	Sprint board, agile workflow	backlog/todo/in-progress/review/done	story/bug/chore
research	Knowledge capture, progressive understanding	captured/processing/understood/connected	note/question/insight/source/synthesis/timeline
exam	Spaced repetition, study	new/learning/reviewing/mastered	concept/formula/flashcard/practice/essay-prompt
general	Lightweight notes + todos	new/active/review/archived	note/reference/idea/todo

Tracker and research are fully implemented. Exam and general are stubs for future development.

Installation

Requires Node.js >= 22.

git clone <repo-url> koji
cd koji
npm install
npm run build

Shell Alias

Add to your .zshrc or .bashrc:

koji() {
  local root
  root=$(git rev-parse --show-toplevel 2>/dev/null)
  if [[ -n "$root" && -d "$root/gojira" ]]; then
    node "$root/gojira/dist/cli.js" "$@"
  else
    node /path/to/koji/dist/cli.js "$@"
  fi
}

For tab completion, add the completions/ directory to your shell's fpath (zsh) or source completions/koji.bash (bash).

Quick Start

# Create a task
koji task new -d ENGINE -t "Implement feature X" -p 3

# Move through statuses
koji task move ENGINE-001 in-progress
koji done ENGINE-001

# View the board
koji board
koji list ENGINE

# Knowledge base
koji know new -t "widget pattern" -d ENGINE -c pattern
koji know dump --ai

# Sprints
koji sprint new --id 2026-W14 --goal "Ship the thing"
koji sprint close 2026-W13

# Search
koji search "feature implementation"

Vendoring Into Other Projects

Use vendor.sh to copy the koji engine into another project:

./vendor.sh /path/to/your-project

This creates your-project/gojira/ with the engine, a starter config, and an empty vault structure. Your project's config (gojira.conf.ts) and vault are preserved on subsequent syncs — only engine files are overwritten.

Multi-Vault with KOJI_VAULT

Override the vault path at runtime without changing config:

# Run against the space program example
KOJI_VAULT=examples/space-program/vault koji know dump --ai

# Point at a shared vault
KOJI_VAULT=/path/to/shared/vault koji board

Presets

Preset template packs live in presets/. Each contains:

presets/<name>/
  conf.template.ts    Default config for this preset
  templates/          Markdown templates (task, epic, sprint, knowledge, etc.)
  views/              Dataview dashboard pages
  guide.md            Methodology guide

Phase 2 will add koji init --preset <name> to scaffold new vaults from a preset.

Space Program Example

A pre-populated research vault demonstrating the research preset:

KOJI_VAULT=examples/space-program/vault koji list --ai
KOJI_VAULT=examples/space-program/vault koji know dump --ai
KOJI_VAULT=examples/space-program/vault koji board --ai

Domains: MERCURY, GEMINI, APOLLO, SHUTTLE, PROPULSION, COLD-WAR. Contains notes on Saturn V, F-1 engine specs, Apollo 11 timeline, combustion instability, and knowledge concepts like staging, escape velocity, and specific impulse.

Project Structure

koji/
  src/
    cli.ts              CLI entry point and command routing
    types.ts            TypeScript interfaces (GojiraConfig, TaskData, etc.)
    gojira.conf.ts      koji's own config (dogfooding)
    lib/                Engine modules (14 files)
  vault/                koji's own task vault
  presets/
    tracker/            Sprint board preset
    research/           Research vault preset
  examples/
    space-program/      Pre-populated research vault demo
  completions/          Zsh and bash tab completions
  vendor.sh             Vendor engine into other projects

Commands

Run koji --help for the full command reference. Highlights:

Command	Alias	Description
koji task new	t n	Create a task
koji task move	t m	Change status
koji list	l, ls	List tasks (filterable)
koji board	b	Kanban board view
koji epic new	e n	Create an epic
koji know dump	k d	Knowledge dump (LLM context)
koji search	find, f	Hybrid text + semantic search
koji sprint new	s n	Create a sprint

Smart shortcuts: koji done PAY-001, koji PAY-001 (show), koji PAY (list domain), koji @mark (list assignee).

License

MIT