# ๐ŸŒธ Miyabi (้›…) **ไธ€ใคใฎใ‚ณใƒžใƒณใƒ‰ใงๅ…จใฆใŒๅฎŒ็ตใ™ใ‚‹่‡ชๅพ‹ๅž‹้–‹็™บใƒ•ใƒฌใƒผใƒ ใƒฏใƒผใ‚ฏ** [![npm version](https://img.shields.io/npm/v/miyabi.svg?style=for-the-badge&color=ff69b4)](https://www.npmjs.com/package/miyabi) [![npm downloads](https://img.shields.io/npm/dm/miyabi.svg?style=for-the-badge&color=ff69b4)](https://www.npmjs.com/package/miyabi) [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=for-the-badge)](https://opensource.org/licenses/MIT) [![Node.js Version](https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=for-the-badge&logo=node.js)](https://nodejs.org) [![GitHub stars](https://img.shields.io/github/stars/ShunsukeHayashi/Miyabi?style=social)](https://github.com/ShunsukeHayashi/Miyabi/stargazers) [![Twitter Follow](https://img.shields.io/twitter/follow/miyabi_dev?style=social)](https://twitter.com/miyabi_dev) **Zero-learning-cost CLI for autonomous AI development** Designed for both humans and AI agents (Claude Code, Devin, etc.) [๐Ÿš€ Quick Start](#-quick-start) โ€ข [๐Ÿ“– Documentation](#-documentation) โ€ข [๐Ÿ’ก Features](#-features) โ€ข [๐Ÿค– For AI Agents](#-ai-agent-integration)
--- ## ๐Ÿ†• What's New in v0.19.0 - **7 Claude Skills** - Reusable workflow templates - `code-reviewer` - Code review with quality scoring - `commit-helper` - Conventional Commits generation - `test-generator` - Unit test generation - `doc-generator` - Documentation generation - `refactor-helper` - Safe refactoring guidance - `skill-creator` - Create custom skills - `autonomous-coding-agent` - CLI automation workflows - **Windows Support** - Full cross-platform compatibility - **Dependencies Updated** - @anthropic-ai/sdk 0.71, @octokit/rest 21 --- ## โœจ What is Miyabi? **Miyabi** (้›… - Japanese for "elegance") transforms your development workflow with **one command**. ```bash npx miyabi init my-project ``` **That's it.** No configuration files. No complex setup. Just pure elegance. ### ๐ŸŽฌ See it in Action
**Before Miyabi:** ``` โŒ Manual repo setup โŒ Configure labels โŒ Setup workflows โŒ Create project boards โŒ Write documentation โŒ Configure CI/CD โฐ Time: 2-3 hours ``` **With Miyabi:** ```bash npx miyabi init my-project โœ“ Repository created โœ“ 53 labels configured โœ“ 12 workflows deployed โœ“ Projects V2 linked โœ“ Documentation generated โœ“ CI/CD ready โฐ Time: 2 minutes ```
### ๐ŸŒŸ Key Highlights

๐Ÿš€ Lightning Fast

Full project setup in under 2 minutes

๐Ÿค– AI-Native

Built for Claude Code & autonomous agents

๐ŸŒธ Zero Config

No learning curve. Just worksโ„ข

๐Ÿ”„ State Machine

53 labels orchestrate your workflow

โšก Auto-Deploy

12+ workflows handle everything

๐ŸŒ i18n Ready

Full Japanese & English support
--- ## ๐Ÿš€ Quick Start > **๐Ÿ“ Note:** Miyabi is currently optimized for **TypeScript/Node.js** projects. For other languages (Python, Go, Rust, etc.), see [Language & Framework Support](#-language--framework-support) below for adaptation instructions. ### For Humans ๐Ÿ‘จโ€๐Ÿ’ป #### Interactive Mode (Easiest) ```bash npx miyabi ``` Then select from the menu: - ๐ŸŒธ **First-Time Setup** (onboarding wizard) - ๐Ÿ†• **Create New Project** - ๐Ÿ“ฆ **Add to Existing Project** - ๐Ÿ“Š **Check Status** - ๐Ÿฉบ **Health Check** (diagnostics) #### One-Command Execution (v0.15.0+) ```bash # Magic command - interactive wizard npx miyabi run # Quick shortcuts npx miyabi fix 123 # Fix issue #123 npx miyabi build 456 # Build feature for issue #456 npx miyabi ship # Deploy with approval gates ``` **Features:** - TUI Dashboard with real-time progress - Human-in-the-loop approval gates for critical actions - One command replaces complex agent orchestration #### Direct Commands ```bash # First-time setup wizard npx miyabi onboard # Health check & diagnostics npx miyabi doctor # Create new project npx miyabi init my-awesome-project # Add to existing project cd existing-project npx miyabi install # Check agent status npx miyabi status --watch ``` ### For AI Agents (Claude Code, Devin) ๐Ÿค– **v0.5.0+** Auto-detects Claude Code and shows CLI commands: ```bash npx miyabi # โ†’ ๐Ÿ’ก Claude Code็’ฐๅขƒใŒๆคœๅ‡บใ•ใ‚Œใพใ—ใŸ # ๅˆฉ็”จๅฏ่ƒฝใชใ‚ณใƒžใƒณใƒ‰: # npx miyabi init # npx miyabi install # npx miyabi status ``` **Direct usage:** ```bash # Create project with all options npx miyabi init my-project --private # Install to existing repo npx miyabi install # Get status npx miyabi status # Configure npx miyabi config ``` --- ## ๐ŸŒธ ใƒ—ใƒญใ‚ฐใƒฉใƒ ใŒ่‹ฆๆ‰‹ใชๆ–นใธ
### ๐Ÿ‘‰ 3ใ‚นใƒ†ใƒƒใƒ—ใงๅฎŒๅ…จ่‡ชๅ‹•ใ‚ปใƒƒใƒˆใ‚ขใƒƒใƒ—
**ใƒ—ใƒญใ‚ฐใƒฉใƒŸใƒณใ‚ฐใฎ็Ÿฅ่ญ˜ใŒใชใใฆใ‚‚ๅคงไธˆๅคซ๏ผ** Claude CodeใŒๅ…จ้ƒจใ‚„ใฃใฆใใ‚Œใพใ™ใ€‚ #### ใ‚นใƒ†ใƒƒใƒ—1: Claude Codeใ‚’ใ‚คใƒณใ‚นใƒˆใƒผใƒซ - [VS Codeๆ‹กๅผตๆฉŸ่ƒฝ](https://marketplace.visualstudio.com/items?itemName=Anthropic.claude-code) - ใพใŸใฏ [claude.ai/code](https://claude.ai/code) #### ใ‚นใƒ†ใƒƒใƒ—2: ้ญ”ๆณ•ใฎ่จ€่‘‰ใ‚’ๅ…ฅๅŠ› ``` /setup-miyabi Miyabiใ‚’ใ‚ปใƒƒใƒˆใ‚ขใƒƒใƒ—ใ—ใฆใใ ใ•ใ„ ``` #### ใ‚นใƒ†ใƒƒใƒ—3: AIใฎ่ณชๅ•ใซ็ญ”ใˆใ‚‹ใ ใ‘๏ผ ใ‚ใจใฏๅ…จ้ƒจ่‡ชๅ‹•ใงใ™ ๐ŸŽ‰
๐Ÿ“– **่ฉณ็ดฐใ‚ฌใ‚คใƒ‰**: [ใƒ—ใƒญใ‚ฐใƒฉใƒ ใŒ่‹ฆๆ‰‹ใชๆ–นๅ‘ใ‘ๅฎŒๅ…จใ‚ฌใ‚คใƒ‰](./FOR_NON_PROGRAMMERS.md) ็”ป้ขใฎใ‚นใ‚ฏใƒชใƒผใƒณใ‚ทใƒงใƒƒใƒˆไป˜ใใƒปๆ‰€่ฆๆ™‚้–“: ็ด„10ๅˆ†
--- ## ๐Ÿ’ก Features ### ๐ŸŽฏ Core Features
One-Command Setup - Everything in one command ```bash npx miyabi init my-project ``` What happens: - โœ… GitHub repository created - โœ… 53 labels configured (state machine) - โœ… 12+ GitHub Actions deployed - โœ… GitHub Projects V2 linked - โœ… Local npm project initialized - โœ… `.claude/` directory with 6 AI agents - โœ… Welcome issue created - โœ… Documentation generated **Time: ~2 minutes**
Label-Based State Machine - Orchestrate your workflow ### 53 Labels Across 10 Categories **States** (7 labels): - `๐Ÿ“ฅ state:pending` โ†’ `๐Ÿ” state:analyzing` โ†’ `๐Ÿ—๏ธ state:implementing` โ†’ `๐Ÿ‘€ state:reviewing` โ†’ `โœ… state:done` **Types** (10 labels): - `๐Ÿ› type:bug` `โœจ type:feature` `๐Ÿ“š type:docs` `โ™ป๏ธ type:refactor` `๐Ÿงช type:test` **Priority** (4 labels): - `๐Ÿ“Š priority:P0-Critical` `โš ๏ธ priority:P1-High` `๐Ÿ“Š priority:P2-Medium` `๐Ÿ“Š priority:P3-Low` **Agents** (6 labels): - `๐Ÿค– agent:coordinator` `๐Ÿค– agent:codegen` `๐Ÿค– agent:review` `๐Ÿค– agent:issue` `๐Ÿค– agent:pr` `๐Ÿค– agent:deploy` **Phase** (8 labels): - `๐ŸŽฏ phase:planning` `๐Ÿ—๏ธ phase:development` `๐Ÿงช phase:testing` `๐Ÿš€ phase:deployment` [View all 53 labels โ†’](./templates/labels.yml)
GitHub Actions Workflows - Complete automation ### 12+ Workflows Included | Workflow | Trigger | Purpose | |----------|---------|---------| | **Autonomous Agent** | Issue opened | Auto-analyze & implement | | **Auto-Label** | Issue/PR opened | Intelligent labeling | | **State Machine** | Label changed | State transitions | | **Auto-Review** | PR opened | Code review | | **Deploy Pages** | Push to main | Docs deployment | | **Economic Circuit Breaker** | High API usage | Cost control | | **Weekly KPI Report** | Schedule | Progress tracking | | **Webhook Router** | All events | Event routing | [View all workflows โ†’](./templates/workflows/)
Claude Code Integration - AI-first development ### Full `.claude/` Directory Deployment **6 AI Agents:** - `CoordinatorAgent` - Task orchestration - `CodeGenAgent` - Code generation - `ReviewAgent` - Quality assurance - `IssueAgent` - Issue management - `PRAgent` - Pull request automation - `DeploymentAgent` - CI/CD **7 Custom Commands:** - `/agent-run` - Run autonomous agent - `/create-issue` - Smart issue creation - `/deploy` - Deploy to production - `/generate-docs` - Auto documentation - `/security-scan` - Security audit - `/test` - Run test suite - `/verify` - System health check **MCP Servers:** - `github-enhanced.js` - Enhanced GitHub integration - `ide-integration.js` - IDE bridging - `project-context.js` - Project awareness [Learn more about Claude Code โ†’](https://claude.ai/code)
### ๐ŸŽจ User Experience
**For Humans:** - โœจ Interactive menus - ๐Ÿ‡ฏ๐Ÿ‡ต Full Japanese support - ๐Ÿ“Š Beautiful status displays - ๐ŸŽฏ Guided setup wizard - โ“ Contextual help **For AI Agents:** - ๐Ÿค– Non-interactive mode - ๐Ÿ“‹ JSON output - ๐Ÿ”ง Programmatic API - ๐ŸŒ Environment variables - ๐Ÿ“– Full context in README
--- ## ๐ŸŒ Language & Framework Support ### Current Implementation (v0.13.0) **Primary Support: TypeScript/Node.js** Miyabi's GitHub Actions and workflows are currently optimized for: - **Language**: TypeScript, JavaScript - **Runtime**: Node.js โ‰ฅ18 - **Package Manager**: npm - **Testing**: Vitest - **Build Tools**: tsc, esbuild **Workflows affected:** - `autonomous-agent.yml` - Uses `npm run typecheck`, `npm run agents:parallel:exec` - `deploy-pages.yml` - Node.js app deployment - `weekly-report.yml` - TypeScript/Node.js implementation - `weekly-kpi-report.yml` - TypeScript/Node.js KPI reporting ### Multi-Language Roadmap **Phase 1 (Current)**: TypeScript/Node.js optimized templates **Phase 2 (v0.14+)**: Language-agnostic workflow templates **Phase 3 (2026+)**: Fully autonomous language detection ### Adapting for Other Languages/Frameworks **You can easily adapt Miyabi for your stack using Claude Code:**
Example: Python + FastAPI ```bash # 1. Install Miyabi (creates TypeScript templates) npx miyabi install # 2. Ask Claude Code to adapt # In Claude Code, run: ``` **Prompt for Claude Code:** ``` .claude/commands ใจ .claude/agents ใซใคใ„ใฆใ€ ๅ…ƒใฎๆŒ‡็คบใฎๆ„ๅ›ณใ‚’ๅค‰ใˆใšใซใ€Python ใจ FastAPI ็”จใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ไปฅไธ‹ใ‚’ๅค‰ๆ›ด: - npm โ†’ pip/poetry - TypeScript โ†’ Python - Vitest โ†’ pytest - tsc โ†’ mypy - Node.js โ†’ Python 3.11+ ใƒฏใƒผใ‚ฏใƒ•ใƒญใƒผใƒ•ใ‚กใ‚คใƒซใ‚‚ๅŒๆง˜ใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ``` **Result:** All workflows adapted for Python!
Example: Go + Gin **Prompt for Claude Code:** ``` .claude/commands ใจ .claude/agents ใซใคใ„ใฆใ€ Go่จ€่ชžใจGinใƒ•ใƒฌใƒผใƒ ใƒฏใƒผใ‚ฏ็”จใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ไปฅไธ‹ใ‚’ๅค‰ๆ›ด: - npm โ†’ go mod - TypeScript โ†’ Go - Vitest โ†’ go test - tsc โ†’ go build - Node.js โ†’ Go 1.21+ ใƒฏใƒผใ‚ฏใƒ•ใƒญใƒผใƒ•ใ‚กใ‚คใƒซใ‚‚ๅŒๆง˜ใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ```
Example: Rust + Actix **Prompt for Claude Code:** ``` .claude/commands ใจ .claude/agents ใซใคใ„ใฆใ€ Rust่จ€่ชžใจActixใƒ•ใƒฌใƒผใƒ ใƒฏใƒผใ‚ฏ็”จใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ไปฅไธ‹ใ‚’ๅค‰ๆ›ด: - npm โ†’ cargo - TypeScript โ†’ Rust - Vitest โ†’ cargo test - tsc โ†’ cargo build - Node.js โ†’ Rust 1.70+ ใƒฏใƒผใ‚ฏใƒ•ใƒญใƒผใƒ•ใ‚กใ‚คใƒซใ‚‚ๅŒๆง˜ใซๆ›ธใๆ›ใˆใฆใใ ใ•ใ„ใ€‚ ```
### Supported Stacks (with adaptation) | Language | Framework | Package Manager | Testing | Status | |----------|-----------|----------------|---------|--------| | TypeScript | Express/Next.js | npm/yarn/pnpm | Vitest | โœ… Native | | JavaScript | React/Vue | npm/yarn/pnpm | Jest | โœ… Native | | Python | FastAPI/Django | pip/poetry | pytest | ๐Ÿ”„ Adapt | | Go | Gin/Echo | go mod | go test | ๐Ÿ”„ Adapt | | Rust | Actix/Rocket | cargo | cargo test | ๐Ÿ”„ Adapt | | Ruby | Rails/Sinatra | bundler | rspec | ๐Ÿ”„ Adapt | | Java | Spring Boot | maven/gradle | junit | ๐Ÿ”„ Adapt | | C# | .NET | nuget | xunit | ๐Ÿ”„ Adapt | **Legend:** - โœ… Native: Works out-of-the-box - ๐Ÿ”„ Adapt: Use Claude Code to adapt workflows ### Best Practices for Adaptation 1. **Keep workflow intentions intact** - Don't change what workflows do, only how they do it 2. **Preserve label system** - The 53-label system is language-agnostic 3. **Maintain agent roles** - CoordinatorAgent, CodeGenAgent, etc. work with any language 4. **Update documentation** - Document your language-specific setup ### Contributing Multi-Language Templates We welcome contributions for other languages! See: - [CONTRIBUTING.md](../../CONTRIBUTING.md) - Contribution guidelines - [docs/MULTI_LANGUAGE_GUIDE.md](../../docs/MULTI_LANGUAGE_GUIDE.md) - Template creation guide --- ## ๐Ÿ“Š Commands Reference ### `init ` Create a new project with full automation. ```bash # Interactive npx miyabi init my-project # With options npx miyabi init my-project --private # Skip npm install npx miyabi init my-project --skip-install ``` **Options:** - `-p, --private` - Create private repository - `--skip-install` - Skip npm install step **What it creates:** ``` my-project/ โ”œโ”€โ”€ .github/ โ”‚ โ”œโ”€โ”€ workflows/ # 12+ GitHub Actions โ”‚ โ””โ”€โ”€ labels.yml # 53 labels โ”œโ”€โ”€ .claude/ โ”‚ โ”œโ”€โ”€ agents/ # 6 AI agents โ”‚ โ”œโ”€โ”€ commands/ # 7 custom commands โ”‚ โ”œโ”€โ”€ hooks/ # Command hooks โ”‚ โ””โ”€โ”€ mcp-servers/ # 3 MCP servers โ”œโ”€โ”€ src/ โ”œโ”€โ”€ package.json โ””โ”€โ”€ README.md ``` --- ### `install` Add Miyabi to an existing project. ```bash # Interactive npx miyabi install # Dry run (preview changes) npx miyabi install --dry-run # Non-interactive mode (CI/CD, Termux, SSH) npx miyabi install --non-interactive npx miyabi install --yes ``` **Options:** - `--dry-run` - Preview changes without making them - `--non-interactive` - Skip all prompts (auto-approve) - `-y, --yes` - Auto-approve all prompts **What it does:** - โœ… Analyzes existing structure - โœ… Merges labels (non-destructive) - โœ… Auto-labels existing issues - โœ… Deploys missing workflows - โœ… Links to Projects V2 - โœ… Creates `.claude/` directory **Smart merge:** - Existing labels are preserved - Workflows skip if already exist - Issues are auto-labeled intelligently --- ### `status` Check agent activity and project status. ```bash # One-time check npx miyabi status # Watch mode (auto-refresh every 10s) npx miyabi status --watch ``` **Output:** ``` โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ” โ”‚ Agent โ”‚ Status โ”‚ Task โ”‚ Last Update โ”‚ โ”œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ผโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ค โ”‚ Coordinator โ”‚ โœ… Active โ”‚ #123 โ”‚ 2 mins ago โ”‚ โ”‚ CodeGen โ”‚ ๐Ÿ’ค Idle โ”‚ - โ”‚ - โ”‚ โ”‚ Review โ”‚ โœ… Active โ”‚ #124 โ”‚ 30 secs ago โ”‚ โ”‚ Issue โ”‚ โœ… Active โ”‚ #125 โ”‚ 1 min ago โ”‚ โ”‚ PR โ”‚ ๐Ÿ’ค Idle โ”‚ - โ”‚ - โ”‚ โ”‚ Deploy โ”‚ โœ… Active โ”‚ main โ”‚ 5 mins ago โ”‚ โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ดโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜ ๐Ÿ“Š Summary: โœ… 4 agents active ๐Ÿ’ค 2 agents idle ๐Ÿ“ฅ 12 pending issues ๐Ÿš€ 3 in progress ``` --- ### `docs` Generate documentation from code. ```bash # Interactive npx miyabi docs # Direct npx miyabi docs --input ./src --output ./docs/API.md # Watch mode npx miyabi docs --watch # Include training materials npx miyabi docs --training ``` **Generates:** - API documentation - Type definitions - Usage examples - Training materials (optional) --- ### `config` Manage Miyabi configuration. ```bash # Interactive wizard npx miyabi config # Show current config npx miyabi config --show # Reset to defaults npx miyabi config --reset ``` **Configuration file** (`.miyabi.yml`): ```yaml github: defaultPrivate: true token: ghp_xxxxx # Or use GITHUB_TOKEN env var project: defaultLanguage: typescript defaultFramework: react gitignoreTemplate: Node licenseTemplate: mit workflows: autoLabel: true autoReview: true autoSync: true cli: language: ja # ja or en theme: default verboseErrors: true ``` --- ### `setup` Interactive setup guide for beginners. ```bash # Interactive mode npx miyabi setup # Non-interactive mode npx miyabi setup --non-interactive # Skip specific steps npx miyabi setup --skip-token --skip-config ``` **Options:** - `--non-interactive` - Skip all prompts - `-y, --yes` - Auto-approve all prompts - `--skip-token` - Skip token setup - `--skip-config` - Skip configuration **Guides through:** 1. โœ… Environment check (Node.js, Git, gh CLI) 2. โœ… GitHub authentication 3. โœ… Token creation 4. โœ… Configuration 5. โœ… First project creation --- ### `onboard` Comprehensive first-run wizard for new users. ```bash # Interactive onboarding npx miyabi onboard # Skip optional features npx miyabi onboard --skip-demo --skip-tour ``` **Options:** - `--skip-demo` - Skip demo project creation - `--skip-tour` - Skip feature tour - `--non-interactive` - Exit (requires interactive mode) - `-y, --yes` - Same as --non-interactive **What it does:** 1. โœ… Welcome & introduction 2. โœ… System health check (calls `doctor`) 3. โœ… 30-second "What is Miyabi?" overview 4. โœ… Demo project creation (optional) 5. โœ… Interactive feature tour 6. โœ… Quick commands reference 7. โœ… Resource links **Perfect for:** - ๐Ÿ†• First-time Miyabi users - ๐Ÿ“š Learning the system - ๐ŸŽ“ Understanding capabilities - ๐Ÿš€ Quick start --- ### `doctor` System health check and diagnostics. ```bash # Basic health check npx miyabi doctor # Detailed diagnostics npx miyabi doctor --verbose # JSON output (for AI agents) npx miyabi doctor --json ``` **Health Checks Performed:** | Check | Description | Fix Suggestions | |-------|-------------|-----------------| | **Node.js** | Version โ‰ฅ18.0.0 | Upgrade Node.js | | **Git** | Installation & version | Install Git | | **GitHub CLI** | `gh` authentication | Run `gh auth login` | | **GITHUB_TOKEN** | Token format validation | Set env var or use gh CLI | | **Token Permissions** | Required scopes check | Add `repo`, `workflow`, `project` | | **Network** | GitHub API connectivity | Check internet connection | | **Repository** | Git repo detection | Initialize git repo | | **.miyabi.yml** | Config file validation | Fix YAML syntax | | **Claude Code** | Environment detection | N/A (informational) | **Output Example:** ``` ๐Ÿฉบ Miyabi Health Check โœ“ Node.js: v20.10.0 (OK) โœ“ Git: git version 2.42.0 (OK) โœ“ GitHub CLI: gh version 2.40.0 (Authenticated) โœ“ GITHUB_TOKEN: Valid token format โš  Token Permissions: Missing recommended scopes: project ๐Ÿ’ก Add recommended scopes for full functionality: https://github.com/settings/tokens โœ“ Network Connectivity: GitHub API accessible โœ“ Repository: Git repository detected โœ“ Claude Code: Standard terminal Summary: โœ“ 7 checks passed โš  1 warnings 8 total checks โš  Overall: Issues detected (but not critical) Next Steps: 1. Review the suggestions above to fix issues 2. Run this command again to verify fixes 3. For help: https://github.com/ShunsukeHayashi/Miyabi/issues ``` **JSON Mode:** ```bash npx miyabi doctor --json ``` ```json { "checks": [ { "name": "Node.js", "status": "pass", "message": "v20.10.0 (OK)", "details": "Node.js v20.10.0 meets minimum requirement (โ‰ฅ18)" }, ... ], "summary": { "passed": 7, "warned": 1, "failed": 0, "total": 8 }, "overallStatus": "issues" } ``` **Exit Codes:** - `0` - Healthy or minor issues - `1` - Critical issues found --- ## ๐Ÿค– AI Agent Integration ### Claude Code Auto-Detection (v0.5.0+) Miyabi automatically detects Claude Code environment and provides CLI-friendly output: ```bash $ npx miyabi โœจ Miyabi ไธ€ใคใฎใ‚ณใƒžใƒณใƒ‰ใงๅ…จใฆใŒๅฎŒ็ตใ™ใ‚‹่‡ชๅพ‹ๅž‹้–‹็™บใƒ•ใƒฌใƒผใƒ ใƒฏใƒผใ‚ฏ ๐Ÿ’ก Claude Code็’ฐๅขƒใŒๆคœๅ‡บใ•ใ‚Œใพใ—ใŸ ๅˆฉ็”จๅฏ่ƒฝใชใ‚ณใƒžใƒณใƒ‰: npx miyabi init - ๆ–ฐ่ฆใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆไฝœๆˆ npx miyabi install - ๆ—ขๅญ˜ใƒ—ใƒญใ‚ธใ‚งใ‚ฏใƒˆใซ่ฟฝๅŠ  npx miyabi status - ใ‚นใƒ†ใƒผใ‚ฟใ‚น็ขบ่ช npx miyabi docs - ใƒ‰ใ‚ญใƒฅใƒกใƒณใƒˆ็”Ÿๆˆ npx miyabi config - ่จญๅฎš็ฎก็† npx miyabi setup - ใ‚ปใƒƒใƒˆใ‚ขใƒƒใƒ—ใ‚ฌใ‚คใƒ‰ ่ฉณ็ดฐ: npx miyabi --help ``` **Detection logic:** - `CLAUDE_CODE=true` - `ANTHROPIC_CLI=true` - `TERM_PROGRAM=Claude` - `ANTHROPIC_API_KEY` is set ### Programmatic API ```typescript import { init, install, status, config } from 'miyabi'; // Initialize new project await init('my-project', { private: true, skipInstall: false, }); // Install to existing project await install({ dryRun: false, }); // Get status const statusData = await status({ watch: false }); console.log(statusData); // Configure await config({ githubToken: process.env.GITHUB_TOKEN, language: 'ja', }); ``` ### Environment Variables ```bash # GitHub token (required) export GITHUB_TOKEN=ghp_your_token_here # Anthropic API key (for AI features) export ANTHROPIC_API_KEY=sk-ant-xxx # Webhook secret (for webhook router) export WEBHOOK_SECRET=your_secret # Non-interactive mode (auto-approve prompts) export MIYABI_AUTO_APPROVE=true # CI environment (auto-detected) export CI=true ``` **Non-Interactive Mode:** Miyabi automatically detects non-interactive environments: - `MIYABI_AUTO_APPROVE=true` - Explicit non-interactive mode - `CI=true` - CI/CD environments (GitHub Actions, GitLab CI, etc.) - Non-TTY terminals - Pipes, redirects, SSH without PTY **Usage in CI/CD:** ```yaml # GitHub Actions example - name: Install Miyabi run: npx miyabi install --non-interactive env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} ``` **Usage in Termux (Android):** ```bash # Termux automatically uses non-interactive mode export MIYABI_AUTO_APPROVE=true npx miyabi install ``` --- ## ๐Ÿ”ง Configuration ### Priority Order 1. **Command-line flags** (highest priority) ```bash npx miyabi config --token=ghp_xxx ``` 2. **Environment variables** ```bash export GITHUB_TOKEN=ghp_xxx ``` 3. **Config file** (`.miyabi.yml`) ```yaml github: token: ghp_xxx ``` 4. **Default values** (lowest priority) ### Configuration File ```yaml github: token: ghp_xxxxx # GitHub Personal Access Token defaultPrivate: true # Create private repos by default defaultOrg: my-org # Default organization project: defaultLanguage: typescript # typescript, javascript, python, go, rust defaultFramework: react # react, vue, angular, next, express gitignoreTemplate: Node # Node, Python, Go, Rust, Java, etc. licenseTemplate: mit # mit, apache-2.0, gpl-3.0, etc. workflows: autoLabel: true # Auto-label new issues autoReview: true # Auto-review PRs autoSync: true # Auto-sync to Projects cli: language: ja # ja (ๆ—ฅๆœฌ่ชž) or en (English) theme: default # default, minimal, colorful verboseErrors: true # Show detailed error messages ``` --- ## ๐Ÿ“‹ Requirements
**Node.js** โ‰ฅ 18.0.0 **Git** Latest **GitHub CLI** Latest **GitHub** Account **Token** PAT
### Installation ```bash # Check requirements node --version # Should be >= 18.0.0 git --version # Any recent version gh --version # Latest stable # Install miyabi (no installation needed for npx) npx miyabi@latest # Or install globally npm install -g miyabi ``` ### GitHub Authentication **Recommended: Use GitHub CLI (automatic)** ```bash # Authenticate once gh auth login # Miyabi will automatically use gh CLI token npx miyabi install # โœ… GitHub authentication complete (via gh CLI) ``` **Alternative: Personal Access Token** If you prefer manual token management, create at: https://github.com/settings/tokens/new **Required scopes:** - โœ… `repo` - Full repository access - โœ… `workflow` - Update workflows - โœ… `write:packages` - Publish packages - โœ… `delete:packages` - Manage packages - โœ… `admin:org` - Organization management (for org repos) - โœ… `project` - Projects V2 access **Token Priority:** 1. **gh CLI** (automatic, recommended) - `gh auth login` 2. **GITHUB_TOKEN** environment variable - `export GITHUB_TOKEN=ghp_xxx` 3. **.env file** - Local development 4. **OAuth flow** - Interactive fallback --- ## ๐Ÿ› Troubleshooting
GITHUB_TOKEN not found **Error:** ``` โŒ GITHUB_TOKEN not found in environment ๐Ÿ’ก ๅฏพๅ‡ฆๆณ•: 1. ็’ฐๅขƒๅค‰ๆ•ฐ GITHUB_TOKEN ใ‚’่จญๅฎšใ—ใฆใใ ใ•ใ„ 2. `export GITHUB_TOKEN=ghp_your_token` 3. ใ‚‚ใ—ใใฏ miyabi config ใ‚’ๅฎŸ่กŒใ—ใฆ่จญๅฎšใ—ใฆใใ ใ•ใ„ ``` **Solution:** **Option 1: Use GitHub CLI (Recommended)** ```bash # One-time setup gh auth login # Miyabi will automatically use gh CLI token npx miyabi install ``` **Option 2: Environment variable** ```bash export GITHUB_TOKEN=ghp_your_token_here npx miyabi init my-project ``` **Option 3: .env file (local development only)** ```bash echo "GITHUB_TOKEN=ghp_your_token" > .env npx miyabi install ``` โš ๏ธ **Security Warning:** - Only use `.env` for local development - Always add `.env` to `.gitignore` - Never commit `.env` to version control - See [SECURITY.md](../../SECURITY.md) for best practices **Option 4: Config file** ```bash npx miyabi config # โ†’ Follow prompts to set token ```
Repository already exists **Error:** ``` โŒ repository creation failed: ใƒชใƒใ‚ธใƒˆใƒชๅ "my-project" ใฏๆ—ขใซๅญ˜ๅœจใ—ใฆใ„ใพใ™ ๐Ÿ’ก ่งฃๆฑบ็ญ–: 1. ๅˆฅใฎๅๅ‰ใ‚’่ฉฆใ—ใฆใใ ใ•ใ„: npx miyabi init my-project-2 2. ใพใŸใฏใ€ๆ—ขๅญ˜ใƒชใƒใ‚ธใƒˆใƒชใ‚’ๅ‰Š้™ค: gh repo delete my-project --yes 3. GitHub ใง็ขบ่ช: https://github.com/settings/repositories ``` **Solution:** Option 1: Different name ```bash npx miyabi init my-project-new ``` Option 2: Delete existing (โš ๏ธ careful!) ```bash gh repo delete my-project --yes npx miyabi init my-project ``` Option 3: Install to existing ```bash gh repo clone my-project cd my-project npx miyabi install ```
Rate limit exceeded **Error:** ``` โŒ GitHub API rate limit exceeded ``` **Solution:** Check rate limit: ```bash gh api rate_limit ``` Wait or use authenticated token: ```bash export GITHUB_TOKEN=ghp_your_token ``` Rate limits: - **Unauthenticated**: 60 requests/hour - **Authenticated**: 5,000 requests/hour
Templates directory not found **Error:** ``` โŒ Claude template directory not found: /path/to/templates/claude-code ``` **Solution:** Reinstall miyabi: ```bash npm uninstall -g miyabi npm cache clean --force npx miyabi@latest init my-project ``` Or use local installation: ```bash git clone https://github.com/ShunsukeHayashi/Miyabi.git cd Miyabi/packages/cli npm install npm run build npm link miyabi init my-project ```
Claude Code not detected **Issue:** Running in Claude Code but interactive mode appears **Solution:** Manually set environment: ```bash export CLAUDE_CODE=true npx miyabi ``` Or use direct commands: ```bash npx miyabi init my-project npx miyabi status ```
`npx miyabi-agent-sdk` ใ‚จใƒฉใƒผ **ใ‚จใƒฉใƒผ:** ``` npm error code ETARGET npm error notarget No matching version found for miyabi-agent-sdk@* ``` **ๅŽŸๅ› :** `miyabi-agent-sdk` ใฏใƒฉใ‚คใƒ–ใƒฉใƒชใงใ‚ใ‚Šใ€CLIใƒ„ใƒผใƒซใงใฏใ‚ใ‚Šใพใ›ใ‚“ใ€‚ `npx miyabi-agent-sdk` ใฎใ‚ˆใ†ใซๅฎŸ่กŒใ™ใ‚‹ใ“ใจใฏใงใใพใ›ใ‚“ใ€‚ **ๆญฃใ—ใ„ไฝฟใ„ๆ–น:** **Option 1: Miyabi CLI ใ‚’ไฝฟ็”จ๏ผˆๆŽจๅฅจ๏ผ‰** ```bash # Miyabi CLI ใ‹ใ‚‰ Agent ใ‚’ๅฎŸ่กŒ npx miyabi agent run codegen --issue=123 npx miyabi agent run review --pr=456 --issue=123 npx miyabi agent run pr --issue=123 ``` **Option 2: ใƒ—ใƒญใ‚ฐใƒฉใƒ ใ‹ใ‚‰็›ดๆŽฅไฝฟ็”จ** ```typescript // package.json { "dependencies": { "miyabi-agent-sdk": "^0.1.0-alpha.2" } } // your-code.ts import { CodeGenAgent } from 'miyabi-agent-sdk'; const agent = new CodeGenAgent({ githubToken: process.env.GITHUB_TOKEN, anthropicApiKey: process.env.ANTHROPIC_API_KEY, }); const result = await agent.generate({ issueNumber: 123, repository: 'my-repo', owner: 'my-org', }); ``` **่ฉณ็ดฐ:** - `miyabi` - CLIใƒ„ใƒผใƒซ๏ผˆ`npx miyabi`ใงๅฎŸ่กŒ๏ผ‰ - `miyabi-agent-sdk` - ใƒฉใ‚คใƒ–ใƒฉใƒช๏ผˆ`import`ใงไฝฟ็”จ๏ผ‰
--- ## ๐Ÿ“š Documentation ### Core Docs - ๐Ÿ“– [Getting Started Guide](./SETUP_GUIDE.md) - Step-by-step setup - ๐ŸŒธ [For Non-Programmers](./FOR_NON_PROGRAMMERS.md) - Complete beginner guide - ๐Ÿ“ฆ [Install to Existing Project](./INSTALL_TO_EXISTING_PROJECT.md) - Migration guide - ๐Ÿงช [Edge Case Tests](./EDGE_CASE_TESTS.md) - Testing scenarios ### Agent Docs - ๐Ÿค– [Agent Operations Manual](../../docs/AGENT_OPERATIONS_MANUAL.md) - Agent system - ๐Ÿ”„ [Webhook Event Bus](../../docs/WEBHOOK_EVENT_BUS.md) - Event routing - ๐Ÿ“‹ [Testing Guide](../../docs/TESTING_GUIDE.md) - Test strategies ### API Reference - ๐Ÿ“ [API Documentation](./docs/API.md) - Full API reference - ๐Ÿ”ง [Configuration Schema](./docs/CONFIG.md) - Config options - ๐Ÿท๏ธ [Label Reference](./templates/labels.yml) - All 53 labels --- ## ๐Ÿ”— Links
[![GitHub](https://img.shields.io/badge/GitHub-Repository-black?style=for-the-badge&logo=github)](https://github.com/ShunsukeHayashi/Miyabi) [![npm](https://img.shields.io/badge/npm-Package-red?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/miyabi) [![Issues](https://img.shields.io/badge/Issues-Report-orange?style=for-the-badge&logo=github)](https://github.com/ShunsukeHayashi/Miyabi/issues) [![Discussions](https://img.shields.io/badge/Discussions-Chat-blue?style=for-the-badge&logo=github)](https://github.com/ShunsukeHayashi/Miyabi/discussions)
--- ## ๐Ÿ™ Acknowledgments Built with love using:

CLI framework
Interactive prompts
Terminal styling
GitHub API client

Claude integration
Type-safe development
Fast unit tests
Modern JS
--- ## ๐Ÿ“„ License
**MIT** ยฉ [Shunsuke Hayashi](https://github.com/ShunsukeHayashi) Open source with โค๏ธ from Tokyo ๐Ÿ—ผ --- **Note for AI Agents:** This README contains full context. All features are documented above. Start by reading the [AI Agent Integration](#-ai-agent-integration) section. ๐ŸŒธ Made with elegance and precision โ€ข [Report Issues](https://github.com/ShunsukeHayashi/Miyabi/issues) โ€ข [Contribute](https://github.com/ShunsukeHayashi/Miyabi/pulls)