tiki/README.md

Follow me on X: [![X Badge](https://img.shields.io/badge/-%23000000.svg?style=flat-square&logo=X&logoColor=white)](https://x.com/booleanandmaybe)

# tiki

**Update:** [v0.5.0 and custom fields](https://github.com/boolean-maybe/tiki/releases/tag/v0.5.0)

`tiki` is a terminal-first Markdown workspace for tasks, docs, prompts, and notes stored in your **git** repo

![Intro](assets/intro.png)

[Documentation](.doc/doki/doc/index.md)

What `tiki` does:

- Standalone **Markdown viewer** with images, Mermaid diagrams, and link/TOC navigation
- Keep, search, view and version Markdown files in the **git repo**
- **Wiki-style** documentation with multiple entry points
- Keep a **to-do list** with priorities, status, assignee and size
- Issue management with **Kanban/Scrum** style board and burndown chart
- SQL-like command language [ruki](.doc/doki/doc/ruki/index.md) to query and update tasks and define custom workflows
- **Plugin-first** architecture - user-defined plugins based on [ruki](.doc/doki/doc/ruki/index.md) and custom views
- AI **skills** to enable [Claude Code](https://code.claude.com), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex](https://openai.com/codex), [Opencode](https://opencode.ai) work with natural language commands like
  "_create a tiki from @my-file.md_"
  "_mark tiki ABC123 as complete_"

## Installation

### Mac OS and Linux
```bash
curl -fsSL https://raw.githubusercontent.com/boolean-maybe/tiki/main/install.sh | bash
```


### Mac OS via brew
```bash
brew install boolean-maybe/tap/tiki
```

### Windows
```powershell
# Windows PowerShell
iwr -useb https://raw.githubusercontent.com/boolean-maybe/tiki/main/install.ps1 | iex
```

### Manual install

Download the latest distribution from the [releases page](https://github.com/boolean-maybe/tiki/releases) 
and simply copy the `tiki` executable to any location and make it available via `PATH`

### Build from source

```bash
git clone https://github.com/boolean-maybe/tiki.git
cd tiki
make build install
```

### Verify installation
```bash
tiki --version
tiki --help
```

## Quick start

### Markdown viewer

![Markdown viewer](assets/markdown-viewer.gif)

`tiki my-markdownfile` to view, edit and navigate markdown files in terminal.
if you have no Markdown file to try - use this:
```
tiki https://github.com/boolean-maybe/tiki/blob/main/testdata/go-concurrency.md
```
see [requirements](.doc/doki/doc/image-requirements.md) for supported terminals, SVG and diagrams support

All vim-like pager commands are supported in addition to:
- `Tab/Enter` to select and load a link in the document
- `e` to edit it in your favorite editor

### File and issue management

<img src=".doc/doki/doc/kanban.gif" alt="Kanban demo" width="800">

to try with a demo project just run:

```
cd /tmp && tiki demo
```

this will clone and show a demo project. Once done you can try your own:

`cd` into your **git** repo and run `tiki init` to initialize.
Move your tiki around the board with `Shift ←/Shift →`.
Press `?` to open the Action Palette — it lists all available actions with their shortcuts.
Press `F1` to open a sample doc root. Follow links with `Tab/Enter`

### AI skills
You will be prompted to install skills for
- [Claude Code](https://code.claude.com)
- [Gemini CLI](https://github.com/google-gemini/gemini-cli)
- [Codex](https://openai.com/codex)
- [Opencode](https://opencode.ai)

if you choose to you can mention `tiki` in your prompts to create/find/edit your tikis
![Claude](assets/claude.png)

### Quick capture

Quick capture ideas by redirecting to `tiki`:
```bash
echo "cool idea" | tiki
gh issue view 42 --json title,body -q '"\(.title)\n\n\(.body)"' | tiki
curl -s https://sentry.io/api/issues/latest/ | jq -r '.title' | tiki
grep ERROR server.log | sort -u | while read -r line; do echo "$line" | tiki; done
```

Read more [quick capture docs](.doc/doki/doc/quick-capture.md).

## tiki
Keep your tickets in your pockets!

`tiki` refers to a task or a ticket (hence tiki) stored in your **git** repo

- like a ticket it can have a status, priority, assignee, points, type and multiple tags attached to it
- they are essentially just Markdown files and you can use full Markdown syntax to describe a story or a bug
- they are stored in `.doc/tiki` subdirectory and are **git**-controlled - they are added to **git** when they are created,
removed when they are done and the entire history is preserved in **git** repo
- because they are in **git** they can be perfectly synced up to the state of your repo or a branch
- you can use either the `tiki` CLI tool or any of the AI coding assistant to work with your tikis

## doki
Store your notes in remotes!

`doki` refers to any file in Markdown format that is stored in the `.doc/doki` subdirectory of the **git** repo. 

- like tikis they are **git**-controlled and can be maintained in perfect sync with the repo state
- `tiki` CLI tool allows creating multiple doc roots like: Documentation, Brainstorming, Prompts etc.
- it also allows viewing and navigation (follow links)

## tiki TUI tool

`tiki` TUI tool allows creating, viewing, editing and deleting tikis as well as creating custom plugins to 
view any selection, for example, Recent tikis, Architecture docs, Saved prompts, Security review, Future Roadmap
Press `?` to open the Action Palette and discover all available actions 

## AI skills

`tiki` adds optional [agent skills](https://agentskills.io/home) to the repo upon initialization
If installed you can:

- work with [Claude Code](https://code.claude.com), [Gemini CLI](https://github.com/google-gemini/gemini-cli), [Codex](https://openai.com/codex), [Opencode](https://opencode.ai) by simply mentioning `tiki` or `doki` in your prompts
- create, find, modify and delete tikis using AI
- create tikis/dokis directly from Markdown files
- Refer to tikis or dokis when implementing with AI-assisted development - `implement tiki xxxxxxx`
- Keep a history of prompts/plans by saving prompts or plans with your repo

## Feedback

Feedback is always welcome! Whether you have an improvement request, a feature suggestion
or just chat:
- use GitHub issues to submit and issue or a feature request
- use GitHub discussions for everything else
- follow and DM on [X](https://x.com/booleanandmaybe)

to contribute:
[Contributing](CONTRIBUTING.md)

## Badges

![Build Status](https://github.com/boolean-maybe/tiki/actions/workflows/go.yml/badge.svg)
[![Go Report Card](https://goreportcard.com/badge/github.com/boolean-maybe/tiki)](https://goreportcard.com/report/github.com/boolean-maybe/tiki)
[![Go Reference](https://pkg.go.dev/badge/github.com/boolean-maybe/tiki.svg)](https://pkg.go.dev/github.com/boolean-maybe/tiki)