Metadata-Version: 2.4
Name: marustorm
Version: 0.1.9
Summary: MaruStorm — AI-powered brainstorming, planning, and memo TUI for vibe coders
Project-URL: Homepage, https://github.com/claudianus/marustorm
Project-URL: Documentation, https://github.com/claudianus/marustorm#readme
Project-URL: Repository, https://github.com/claudianus/marustorm
Project-URL: Issues, https://github.com/claudianus/marustorm/issues
Author-email: "Ryan H. Park" <claudianus@engineer.com>
License: Apache-2.0
License-File: LICENSE
Keywords: ai,brainstorming,llm,markdown,notes,productivity,research,terminal,tui,writing
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Office/Business :: Scheduling
Classifier: Topic :: Text Processing :: Markup
Classifier: Typing :: Typed
Requires-Python: >=3.12
Requires-Dist: agent-client-protocol==0.8.0
Requires-Dist: aiofiles<26.0,>=24.0
Requires-Dist: aiohttp==3.13.3
Requires-Dist: fastapi>=0.115.0
Requires-Dist: fastmcp==2.12.5
Requires-Dist: httpx[socks]==0.28.1
Requires-Dist: jinja2==3.1.6
Requires-Dist: keyring>=25.7.0
Requires-Dist: loguru<0.8,>=0.6.0
Requires-Dist: lxml==6.0.2
Requires-Dist: markdown-it-py>=3.0.0
Requires-Dist: pillow==12.1.0
Requires-Dist: prompt-toolkit==3.0.52
Requires-Dist: pydantic==2.12.5
Requires-Dist: pyyaml==6.0.3
Requires-Dist: rich==14.2.0
Requires-Dist: ripgrepy==2.2.0
Requires-Dist: scalar-fastapi>=1.5.0
Requires-Dist: setproctitle>=1.3.0
Requires-Dist: sqlite-vec>=0.1.0
Requires-Dist: streamingjson==0.0.5
Requires-Dist: tenacity==9.1.2
Requires-Dist: textual>=1.0.0
Requires-Dist: tomlkit==0.14.0
Requires-Dist: trafilatura==2.0.0
Requires-Dist: typer==0.21.1
Requires-Dist: uvicorn[standard]>=0.32.0
Requires-Dist: websockets>=14.0
Provides-Extra: dev
Requires-Dist: pyright>=1.1.407; extra == 'dev'
Requires-Dist: pytest-asyncio>=1.3.0; extra == 'dev'
Requires-Dist: pytest>=9.0.2; extra == 'dev'
Requires-Dist: ruff>=0.14.10; extra == 'dev'
Provides-Extra: research
Requires-Dist: maru-deep-pro-search[semantic]>=0.1.0; extra == 'research'
Description-Content-Type: text/markdown

<div align="center">

# ⛈️ MaruStorm

> **Scatter → Research → Swarm → Weave**

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

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

[![PyPI](https://img.shields.io/pypi/v/marustorm?color=blue&label=PyPI)](https://pypi.org/project/marustorm/)
[![Python](https://img.shields.io/badge/python-3.12%2B-blue)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green)](LICENSE)
[![CI](https://github.com/claudianus/marustorm/actions/workflows/ci.yml/badge.svg)](https://github.com/claudianus/marustorm/actions)
[![GitHub Stars](https://img.shields.io/github/stars/claudianus/marustorm?style=social)](https://github.com/claudianus/marustorm)

[English](#english) · [한국어](#korean)

</div>

---

<a id="english"></a>

## 🇺🇸 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):

```bash
# 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+?**

```bash
pip install marustorm
```

**From source:**

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

### Quick Start

```bash
# 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

```toml
# ~/.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

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

# Format
ruff check src/marustorm tests

# Type check
pyright src/marustorm
```

---

<a id="korean"></a>

## 🇰🇷 한국어

### MaruStorm이 뭔가요?

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

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

### 설치

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

```bash
# 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+가 있다면:**

```bash
pip install marustorm
```

**소스에서:**

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

### 빠른 시작

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

# TUI 실행
marustorm

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

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

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

# 그래프 통계
marustorm graph

# GitHub 동기화
marustorm sync
```

### 설정

```toml
# ~/.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)
```

### 개발

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

# 포맷팅
ruff check src/marustorm tests

# 타입 체크
pyright src/marustorm
```

---

## License / 라이선스

[Apache-2.0](LICENSE) — forked from [MoonshotAI/kimi-cli](https://github.com/MoonshotAI/kimi-cli)
