akiflow-toolkit

Unofficial project. Not affiliated with Akiflow Inc. Uses reverse-engineered internal API. May break without notice. See DISCLAIMER.md.

Unofficial CLI and MCP server for Akiflow, enabling terminal-based task management and AI agent integration (Claude Code, Cursor, Claude Desktop).

Status

Alpha — Published to npm as akiflow-toolkit. Requires Bun 1.1+ runtime.

Planned Features

• CLI (af): Task management from terminal — add, list, complete, schedule, projects, calendar
• MCP Server (af --mcp): AI agent integration via Model Context Protocol
• Auto Authentication: Extracts tokens from browser data (IndexedDB, cookies) — no manual DevTools copy
• Token Auto-Recovery: 3-tier recovery when tokens expire (refresh → disk reload → browser re-extract)
• Cross-browser: Chrome, Arc, Brave, Edge, Safari support (macOS)

Architecture

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

• ADR Index — All 15 ADRs
• Highlights: Bun runtime, Hexagonal (Ports & Adapters), Outcome-first MCP Tools, semantic-release, Test Diamond

Runtime Requirement — Bun Only

akiflow-toolkit은 Bun 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/ 참고).

Installation

Prerequisites

Bun 1.1+ 설치:

# macOS / Linux
curl -fsSL https://bun.sh/install | bash

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

Install CLI

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+	✅	✅	❌ (manual af auth only)	Partial — see docs/tasks/linux-support.md
Windows (x64)	Bun 1.1+	✅	✅	❌ (manual af auth only)	Partial — see docs/tasks/windows-support.md

macOS

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

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

Linux

CLI 및 MCP는 정상 동작합니다. Chrome cookie 자동 추출은 미구현(libsecret 미연동)이므로 수동 인증을 사용합니다.

bun install -g akiflow-toolkit

# 수동 인증: Akiflow 웹 로그인 후 DevTools → Network → request headers에서
# Bearer <JWT>를 복사해 붙여넣기
af auth

af ls

제약 사항:

• Chrome cookie 기반 auto-auth 미지원
• Safari 관련 기능 없음 (Apple 전용 브라우저)

Windows

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

PowerShell에서:

bun install -g akiflow-toolkit
af auth        # 수동 입력
af ls

제약 사항:

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

From Source (development)

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

Quick Start

Coming soon after initial implementation.

# Authenticate (auto-extracts from browser)
af auth

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

# Setup MCP for Claude Code
af setup claude-code

Verifying authentication

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

# 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
#    MCP: register `af --mcp` in ~/.claude.json and ask
#    Claude Code "오늘 할 일 보여줘".

If something fails, read 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:

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

• CLI Commands (coming soon)
• MCP Tools (coming soon)
• Authentication Guide (coming soon)
• Architecture Decisions
• Contributing (coming soon)

Development

Prerequisites

• Bun >= 1.0.0
• pre-commit (brew install pre-commit or pip install pre-commit)

Setup

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

Commands

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

Local MCP registration (before npm publish)

Until akiflow-toolkit lands on npm, you can still use it from Claude Code / Cursor / Claude Desktop by building a standalone binary and symlinking it into your PATH. af setup performs an atomic merge-write on the editor config, so any existing mcpServers entries are preserved.

Install

# 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
# 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.

Uninstall

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

# 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.

License

MIT © kty1965