# akiflow-toolkit

> **Unofficial project.** Not affiliated with Akiflow Inc.
> Uses reverse-engineered internal API. May break without notice.
> See [DISCLAIMER.md](./DISCLAIMER.md).

Unofficial CLI and MCP server for [Akiflow](https://akiflow.com), enabling terminal-based task management and AI agent integration (Claude Code, Cursor, Claude Desktop).

## Status

**Alpha** — Published to npm as `akiflow-toolkit`. Requires **[Bun](https://bun.sh) 1.1+** runtime.

## Features

- **CLI** (`af`): Task management from terminal — add, list, complete, schedule, projects, calendar
- **MCP Server**: AI agent integration via Model Context Protocol
  - `af --mcp` — stdio, one server per editor session
  - `af --mcp --http` — one shared Streamable HTTP server for every session ([details](#shared-mcp-server-http))
- **Auto Authentication**: Extracts tokens from browser data (IndexedDB, cookies) on macOS, or opens a Chrome login window via CDP — no manual DevTools copy
- **Token Auto-Recovery**: refreshes the access token 2 minutes before it expires, keeps a long-running MCP server authenticated while idle, and on a 401 falls back through refresh → disk reload → browser re-extract. Refreshes are serialized across processes (`auth.json.lock`) so the CLI and the MCP server don't refresh at the same time.
- **Cross-browser**: Chrome, Arc, Brave, Edge, Safari support (macOS)

## Architecture

Key decisions are documented as Architecture Decision Records (ADRs):

- [ADR Index](./docs/adr/README.md) — All 16 ADRs
- Highlights: Bun runtime, Hexagonal (Ports & Adapters), Outcome-first MCP Tools, semantic-release, Test Diamond

## Runtime Requirement — **Bun Only**

`akiflow-toolkit`은 [Bun](https://bun.sh) runtime 전용 CLI입니다. Node.js로는 실행할 수 없습니다.

- 배포 번들이 `bun:sqlite` 등 Bun 네이티브 모듈을 직접 사용합니다 (Chrome cookie DB 파싱 용도).
- shebang이 `#!/usr/bin/env bun`으로 고정되어 있습니다.
- Bun은 Node.js 호환 API를 대부분 지원하므로 기능적 제약은 거의 없습니다.

> Node.js 지원이 필요하면 `better-sqlite3`로 교체하는 별도 마이그레이션이 필요합니다 ([docs/tasks/](./docs/tasks/) 참고).

## Installation

### Prerequisites

Bun 1.1+ 설치:
```bash
# macOS / Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
powershell -c "irm bun.sh/install.ps1 | iex"
```

### Install CLI

```bash
bun install -g akiflow-toolkit
af --help
```

## Platform Support

| Platform | Runtime | CLI core | MCP server | Auto auth (browser) | Status |
|----------|---------|----------|-----------|---------------------|--------|
| **macOS** (arm64/x64) | Bun 1.1+ | ✅ | ✅ | ✅ Chrome/Arc/Brave/Edge/Safari | **Fully supported** |
| **Linux** (x64/arm64) | Bun 1.1+ | ✅ | ✅ | ⚠️ CDP login window (no cookie extraction) | **Partial** — see [docs/tasks/linux-support.md](./docs/tasks/linux-support.md) |
| **Windows** (x64) | Bun 1.1+ | ✅ | ✅ | ❌ (`af auth --manual` only) | **Partial** — see [docs/tasks/windows-support.md](./docs/tasks/windows-support.md) |

### macOS

자동 인증 포함 전체 기능이 동작합니다.

```bash
bun install -g akiflow-toolkit
af auth        # Chrome/Arc/Brave/Edge/Safari에서 자동 토큰 추출
af ls
```

### Linux

CLI 및 MCP는 정상 동작합니다. Chrome cookie 자동 추출은 미구현(libsecret 미연동)이지만, `af auth` 가
Chrome/Chromium 을 CDP 모드로 띄워 로그인 창을 열고 토큰을 가져옵니다. 이후 갱신은 refresh token 으로 자동 처리됩니다.

```bash
bun install -g akiflow-toolkit

# Chrome/Chromium 로그인 창이 열림 → Akiflow 로그인 → 토큰 저장
af auth
# 브라우저를 띄울 수 없는 환경(SSH 등)에서는 refresh token 을 직접 입력
# af auth --manual < refresh-token.txt   # refresh token 을 stdin 으로 전달

af ls
```

제약 사항:
- Chrome cookie 기반 auto-auth 미지원 (CDP 로그인 창 또는 `af auth --manual`)
- CDP 로그인에는 데스크톱 세션과 `google-chrome`/`chromium` 이 필요
- Safari 관련 기능 없음 (Apple 전용 브라우저)

### Windows

CLI 및 MCP는 동작합니다. DPAPI(Windows 쿠키 암호화) 미연동으로 Chrome cookie 자동 추출은 불가능.

PowerShell에서:
```powershell
bun install -g akiflow-toolkit
Get-Content refresh-token.txt | af auth --manual   # refresh token 을 stdin 으로 전달
af ls
```

제약 사항:
- Bun Windows arm64는 실험 단계 (x64 권장)
- PowerShell용 completion 스크립트 미제공 (bash/zsh/fish만 지원)
- Chrome cookie 기반 auto-auth 미지원

### From Source (development)

```bash
git clone https://github.com/kty1965/akiflow-toolkit.git
cd akiflow-toolkit
bun install
bun run dev
```

## Quick Start

```bash
# Authenticate (auto-extracts from browser)
af auth

# Use CLI
af ls
af add "New task" --today

# Setup MCP for Claude Code (stdio)
af setup claude-code
# or share one server across sessions: see below
```

### Shared MCP server (HTTP)

`af --mcp` (stdio) starts a separate server for every Claude Code session. To share one
server — one auth keep-alive, one token refresh — across all sessions, run the HTTP mode:

```bash
# 1. Run the server (127.0.0.1:7823/mcp; override with AF_MCP_HTTP_PORT)
af --mcp --http

# 2. Point Claude Code at it (writes { type: "http", url, headers } to ~/.claude.json)
af setup claude-code --http
```

Requests must carry `Authorization: Bearer <token>`. The token is generated on first start
at `~/.config/akiflow/mcp-http-token` (mode 0600) and copied into the Claude Code config by
`setup --http`.

To keep the server running on Linux, install the systemd user unit:

```bash
mkdir -p ~/.config/systemd/user
cp contrib/systemd/akiflow-mcp.service ~/.config/systemd/user/
# edit ExecStart if af is not at ~/.local/bin/af
systemctl --user daemon-reload
systemctl --user enable --now akiflow-mcp
journalctl --user -u akiflow-mcp -f      # logs
```

User services stop at logout unless lingering is enabled (`loginctl enable-linger $USER`).

### Verifying authentication

After `af auth`, you can confirm the CLI is talking to the real Akiflow API at four levels of depth:

```bash
# 1. Is a credential stored?
af auth status
# → Authenticated: active
#     source: indexeddb
#     expiresAt: 2026-04-19T13:28:30.768Z

# 2. Does the stored token actually reach Akiflow API? (diagnostic probe)
bun run scripts/mcp-api-probe.ts
# → ✓ Akiflow API reachable AND token accepted.
#   status 200 OK, body length 5MB+

# 3. Can a real MCP client spawn the server and round-trip a task?
bun run scripts/mcp-live-demo.ts
# → runs 9 steps: spawn → tools/list → auth_status → READ precheck
#   → create_task → verify inbox → complete_task → verify done
# A clean run ends with "✓ All Tier 2 E2E checks passed."

# 4. Try it from your editor
#    af setup claude-code (or --http), restart Claude Code, then ask
#    "오늘 할 일 보여줘".
```

**If something fails**, read [`docs/akiflow-token-acquisition.md`](./docs/akiflow-token-acquisition.md) — it walks through the dual auth scheme (Laravel session cookie vs OAuth JWT), the 4-tier extraction cascade (IndexedDB → Cookie → Safari → Manual), the `withAuth` recovery sequence, and six known failure modes with concrete fixes.

Most common remedy when `auth_status` shows `source: cookie` but API calls throw `fetch failed` / `Header has invalid value`:

```bash
osascript -e 'tell application "Google Chrome" to quit'   # release leveldb LOCK
bun run src/index.ts auth logout
bun run src/index.ts auth                                 # re-scan IndexedDB
bun run src/index.ts auth status                          # expect source: indexeddb
```

## Documentation

- [Authentication & token acquisition](./docs/akiflow-token-acquisition.md)
- [Architecture Decisions](./docs/adr/README.md)
- Platform notes: [Linux](./docs/tasks/linux-support.md), [Windows](./docs/tasks/windows-support.md)
- CLI reference: `af --help`, `af <command> --help`

## Development

### Prerequisites

- [Bun](https://bun.sh) >= 1.1.0
- [pre-commit](https://pre-commit.com) (`brew install pre-commit` or `pip install pre-commit`)

### Setup

```bash
git clone https://github.com/kty1965/akiflow-toolkit.git
cd akiflow-toolkit
bun install
pre-commit install --install-hooks
```

### Commands

```bash
bun run dev          # Hot reload 개발 모드
bun test             # 테스트 실행
bun run lint         # Biome 린트
bun run build        # npm 배포용 dist/ 빌드
bun run build:binary # 크로스 플랫폼 바이너리 빌드
```

### Local binary registration

To run an unreleased build from Claude Code / Cursor / Claude Desktop, build a standalone binary and symlink it into your `PATH` (it takes precedence over a global `bun install -g` copy when `~/.local/bin` comes first). `af setup` performs an atomic merge-write on the editor config, so any existing `mcpServers` entries are preserved.

#### Install

```bash
# 1. Build a self-contained binary for your platform (Bun runtime embedded)
bun run build:darwin-arm64   # Apple Silicon
# bun run build:darwin-x64   # Intel Mac
# bun run build:linux-x64    # Linux x64
# bun run build:linux-arm64  # Linux arm64

# 2. Symlink into a PATH directory (no sudo required)
mkdir -p ~/.local/bin
ln -sf "$PWD/dist/af-darwin-arm64" ~/.local/bin/af

# 3. Make sure ~/.local/bin is on PATH
echo "$PATH" | tr ':' '\n' | grep -q "$HOME/.local/bin" \
  || echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
# Open a new shell, or: source ~/.zshrc

# 4. Smoke check
af --help
af auth status               # expect: source: indexeddb, active

# 5. Register the MCP server in your AI editor
af setup claude-code         # → ~/.claude.json (stdio)
# af setup claude-code --http  # → shared HTTP server (run `af --mcp --http` or the systemd unit)
# af setup cursor            # → ~/.cursor/mcp.json
# af setup claude-desktop    # → ~/Library/Application Support/Claude/... (macOS only)

# 6. Restart the editor, then try a tool call (e.g. "show me today's inbox")
```

When you edit source code later, only step 1 needs to run again — the symlink keeps pointing at the fresh binary. If you run the shared HTTP server, restart it too (`systemctl --user restart akiflow-mcp`).

#### Uninstall

```bash
# 1. Remove the akiflow entry from every editor config where it was registered
jq 'del(.mcpServers.akiflow)' ~/.claude.json > ~/.claude.json.new && mv ~/.claude.json.new ~/.claude.json
[ -f ~/.cursor/mcp.json ] && jq 'del(.mcpServers.akiflow)' ~/.cursor/mcp.json > ~/.cursor/mcp.json.new && mv ~/.cursor/mcp.json.new ~/.cursor/mcp.json
# Claude Desktop (macOS):
#   CONFIG=~/Library/Application\ Support/Claude/claude_desktop_config.json
#   jq 'del(.mcpServers.akiflow)' "$CONFIG" > "$CONFIG".new && mv "$CONFIG".new "$CONFIG"

# 1b. If you used the shared HTTP server
systemctl --user disable --now akiflow-mcp
rm -f ~/.config/systemd/user/akiflow-mcp.service ~/.config/akiflow/mcp-http-token
systemctl --user daemon-reload

# 2. Remove the PATH shim
rm -f ~/.local/bin/af

# 3. (Optional) Drop the compiled binaries
rm -rf dist/

# 4. (Optional) Revoke stored auth credentials
bun run src/index.ts auth logout    # or: rm ~/.config/akiflow/auth.json

# 5. Restart the editor
```

## Disclaimer

See [DISCLAIMER.md](./DISCLAIMER.md).

## License

MIT © kty1965