marustorm 0.2.1

MaruStorm — AI-powered brainstorming, planning, and memo TUI for vibe coders

⛈️ MaruStorm

Scatter → Research → Swarm → Weave

A terminal-native, AI-powered brainstorming & note-weaving engine for vibe coders.

터미널 기반 AI 브레인스토밍 & 노트 짜임 엔진

English · 한국어

---

🇺🇸 English

What is MaruStorm?

MaruStorm is a terminal-first knowledge workbench that lives in your shell. No browser tabs. No SaaS subscriptions. Just you, your terminal, and AI.

• 📝 Markdown Note Editor — YAML frontmatter, inline AI citations, ghost text
• 🔬 Deep Research — AI researches before answering, with source citations [1], [2]
• 🐝 Swarm Writing — Writer / Researcher / Critic / Synthesizer agents in parallel
• 🕸️ Graph View — Navigate ideas as a connected knowledge graph
• ☁️ GitHub Sync — Your notes live in a private GitHub repo (zero server cost)
• 🖥️ Beautiful TUI — Textual-powered 3-pane interface

Installation

One-liner (auto-detects Python, installs everything):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/claudianus/marustorm/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/claudianus/marustorm/main/install.ps1 | iex

The installer will:

1. Install uv (fast Python package manager) if missing
2. Install Python 3.13 if your system Python is older than 3.12
3. Install marustorm + all dependencies
4. Initialize your workspace at ~/marustorm-notes

Already have Python 3.12+?

pip install marustorm

From source:

git clone https://github.com/claudianus/marustorm.git
cd marustorm
pip install -e ".[dev]"

Quick Start

# Initialize config and note structure
marustorm init

# Launch the TUI
marustorm

# Create a new note
marustorm new "My Idea" --tags idea,vibe

# Search notes
marustorm search "AI agents"

# Research a topic
marustorm research "quantum computing"

# Show graph stats
marustorm graph

# Sync to GitHub
marustorm sync

Configuration

# ~/.marustorm/config.toml
[storage]
notes_dir = "~/Notes"
github_repo = "yourname/notes"
github_branch = "main"
auto_sync = false
sync_interval_s = 300

[providers.openai]
type = "openai"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."

[models.gpt4o]
provider = "openai"
model = "gpt-4o"
max_context_size = 128000

The Workflow

Phase	What happens
1. Scatter	Jot raw ideas. MaruStorm auto-parses YAML frontmatter and builds a tag graph.
2. Research	Press Ctrl+R. MaruStorm calls deep search, gathers sources before answering.
3. Swarm	Press Ctrl+W. 4 agents run in parallel: Writer, Researcher, Critic, Synthesizer.
4. Weave	Final note inserted into editor. Citations have hover previews. Tags link to related notes.

Keyboard Shortcuts

Key	Action
Ctrl+N	New Note
Ctrl+S	Save
Ctrl+R	Toggle Research
Ctrl+W	Spawn Swarm
Ctrl+G	Toggle Graph
Ctrl+L	Toggle AI Panel
Ctrl+T	Toggle Thinking
Ctrl+F	Search
Ctrl+Q	Quit
Esc	Focus Mode

Architecture

marustorm/
├── brain/          # BrainEngine — intent routing, slash commands, swarm spawn
├── notes/          # NoteManager — CRUD, frontmatter, parser, graph
├── research/       # MaruStormResearchEngine — deep search harness
├── search/         # Local inverted-index search
├── storage/        # GitHub sync (httpx), disk cache
├── tui/            # Textual widgets (nav, editor, AI panel, graph, research, thinking)
├── skills/         # YAML skill templates (brainstorm, PRD, market research, daily memo)
├── auth/           # OAuth Device Flow
└── mcp/            # MCP gateway (FastMCP)

Development

# Run tests
pytest tests/test_*.py -v

# Format
ruff check src/marustorm tests

# Type check
pyright src/marustorm

---

🇰🇷 한국어

MaruStorm이 뭔가요?

MaruStorm은 터미널 안에서 작동하는 AI 지식 워크벤치입니다. 브라우저 탭도, SaaS 구독도 필요 없습니다. 터미널과 AI만 있으면 됩니다.

• 📝 마크다운 노트 에디터 — YAML 프론트매터, 인라인 AI 인용, 고스트 텍스트
• 🔬 딥 리서치 — AI가 답변 전에 먼저 연구하고, 출처 인용 [1], [2]
• 🐝 스웜 라이팅 — 작가/연구원/비평가/종합자 에이전트가 병렬로 작업
• 🕸️ 그래프 뷰 — 연결된 지식 그래프로 아이디어 탐색
• ☁️ GitHub 동기화 — 노트가 프라이빗 GitHub 레포에 저장됨 (서버 비용 0)
• 🖥️ 아름다운 TUI — Textual 기반 3-패인 인터페이스

설치

원라인 설치 (Python 버전 자동 감지, 전부 자동 설치):

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/claudianus/marustorm/main/install.sh | bash

# Windows PowerShell
irm https://raw.githubusercontent.com/claudianus/marustorm/main/install.ps1 | iex

설치 스크립트가 하는 일:

1. uv가 없으면 자동 설치 (빠른 Python 패키지 매니저)
2. 시스템 Python이 3.12 미만이면 Python 3.13 자동 설치
3. marustorm + 모든 의존성 설치
4. ~/marustorm-notes 워크스페이스 초기화

이미 Python 3.12+가 있다면:

pip install marustorm

소스에서:

git clone https://github.com/claudianus/marustorm.git
cd marustorm
pip install -e ".[dev]"

빠른 시작

# 설정 및 노트 폴터 초기화
marustorm init

# TUI 실행
marustorm

# 새 노트 작성
marustorm new "내 아이디어" --tags idea,vibe

# 노트 검색
marustorm search "AI 에이전트"

# 주제 연구
marustorm research "양자 컴퓨팅"

# 그래프 통계
marustorm graph

# GitHub 동기화
marustorm sync

설정

# ~/.marustorm/config.toml
[storage]
notes_dir = "~/Notes"
github_repo = "yourname/notes"
github_branch = "main"
auto_sync = false
sync_interval_s = 300

[providers.openai]
type = "openai"
base_url = "https://api.openai.com/v1"
api_key = "sk-..."

[models.gpt4o]
provider = "openai"
model = "gpt-4o"
max_context_size = 128000

워크플로우

단계	설명
1. Scatter	날것의 아이디어를 적습니다. MaruStorm이 YAML 프론트매터를 파싱하고 태그 그래프를 자동 구축합니다.
2. Research	Ctrl+R을 누릅니다. MaruStorm이 딥 서치를 호출해 답변 전에 출처를 수집합니다.
3. Swarm	Ctrl+W를 누릅니다. 4개의 에이전트가 병렬로 실행됩니다: 작가, 연구원, 비평가, 종합자.
4. Weave	최종 노트가 에디터에 삽입됩니다. 인용에는 호버 프리뷰가 있고, 태그는 관련 노트로 연결됩니다.

키보드 단축키

키	동작
Ctrl+N	새 노트
Ctrl+S	저장
Ctrl+R	연구 패널 토글
Ctrl+W	스웜 실행
Ctrl+G	그래프 토글
Ctrl+L	AI 패널 토글
Ctrl+T	Thinking 패널 토글
Ctrl+F	검색
Ctrl+Q	종료
Esc	포커스 모드

아키텍처

marustorm/
├── brain/          # BrainEngine — 인텐트 라우팅, 슬래시 명령, 스웜 생성
├── notes/          # NoteManager — CRUD, 프론트매터, 파서, 그래프
├── research/       # MaruStormResearchEngine — 딥 서치 하네스
├── search/         # 로컬 역인덱스 검색
├── storage/        # GitHub 동기화(httpx), 디스크 캐시
├── tui/            # Textual 위젯 (내비, 에디터, AI 패널, 그래프, 연구, Thinking)
├── skills/         # YAML 스킬 템플릿 (브레인스토밍, PRD, 시장조사, 데일리 메모)
├── auth/           # OAuth 디바이스 플로우
└── mcp/            # MCP 게이트웨이 (FastMCP)

개발

# 테스트 실행
pytest tests/test_*.py -v

# 포맷팅
ruff check src/marustorm tests

# 타입 체크
pyright src/marustorm

---

License / 라이선스

Apache-2.0 — forked from MoonshotAI/kimi-cli