{"id":50240936,"url":"https://github.com/shigenoko/hokusai","last_synced_at":"2026-05-26T21:01:12.427Z","repository":{"id":353791929,"uuid":"1220894345","full_name":"shigenoko/hokusai","owner":"shigenoko","description":"LangGraph-based AI development workflow automation with Claude Code integration","archived":false,"fork":false,"pushed_at":"2026-05-22T07:42:23.000Z","size":2686,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-22T09:28:32.850Z","etag":null,"topics":["ai","claude-code","developer-tools","human-in-the-loop","langgraph","python","workflow-automation"],"latest_commit_sha":null,"homepage":"https://github.com/shigenoko/hokusai","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shigenoko.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T13:31:48.000Z","updated_at":"2026-05-22T07:42:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/shigenoko/hokusai","commit_stats":null,"previous_names":["shigenoko/hokusai"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/shigenoko/hokusai","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shigenoko%2Fhokusai","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shigenoko%2Fhokusai/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shigenoko%2Fhokusai/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shigenoko%2Fhokusai/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shigenoko","download_url":"https://codeload.github.com/shigenoko/hokusai/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shigenoko%2Fhokusai/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33538660,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"ssl_error","status_checked_at":"2026-05-26T15:22:15.568Z","response_time":63,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","claude-code","developer-tools","human-in-the-loop","langgraph","python","workflow-automation"],"created_at":"2026-05-26T21:00:59.209Z","updated_at":"2026-05-26T21:01:12.416Z","avatar_url":"https://github.com/shigenoko.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# HOKUSAI\n\n**HOKUSAI** = **H**uman-**O**rchestrated **K**nowledge \u0026 **U**nified **S**ystem for **A**I **I**ntegration\n\nLangGraph-based AI development workflow automation that orchestrates multiple LLMs.\n\n[日本語版 README はこちら](./README_JP.md)\n\n## Overview\n\nHOKUSAI orchestrates a 10-phase development workflow that automates research, planning, implementation, verification, review, and pull-request management. It is built on [LangGraph](https://github.com/langchain-ai/langgraph) and integrates with multiple LLM-based coding agents (e.g., [Claude Code](https://claude.com/claude-code)) and the GitHub CLI (`gh`).\n\nThe name reflects the design philosophy: **humans orchestrate** decisions and review, while a **unified system** integrates AI tooling for the heavy lifting. Each phase can pause for human input, and the unified review loop in Phase 8 handles Copilot and human review comments in any order — making the workflow safe and predictable for **Human-in-the-Loop (HITL)** development.\n\n## Why HOKUSAI?\n\n**AI alone is not enough.**\n\nTo use AI in real-world systems — especially in regulated industries — you need:\n\n- **Control**\n- **Accountability**\n- **Repeatability**\n\nHOKUSAI is a human-centered AI workflow system designed for organizations where **trust, accountability, and control matter**.\n\nIn industries like finance, payments, and enterprise systems, AI cannot operate unchecked. Every decision must be **explainable, auditable, and ultimately owned by a human**.\n\nHOKUSAI bridges this gap.\n\nIt transforms fragmented AI usage into a structured, repeatable workflow where:\n\n- **AI accelerates execution**\n- **Humans retain control and responsibility**\n- **Knowledge and processes are standardized**\n- **Every step is traceable and auditable**\n\nRather than replacing humans, HOKUSAI orchestrates AI around them.\n\nIt provides a unified framework to integrate AI into real-world operations — safely, transparently, and at scale.\n\n## The Problem\n\nAI adoption in enterprise environments is fragmented and difficult to control.\n\n- AI usage is inconsistent across teams\n- Prompts and workflows are not standardized\n- Outputs are not always traceable or auditable\n- Human responsibility is unclear\n\nIn regulated industries such as finance and payments, this makes it difficult to safely scale AI usage.\n\n## The Solution\n\nHOKUSAI provides a structured, human-in-the-loop workflow for AI integration.\n\nIt transforms ad-hoc AI usage into a repeatable and controlled process where:\n\n- AI accelerates execution\n- Humans retain decision-making authority\n- Knowledge and processes are standardized\n- Every step is traceable and auditable\n\n## Architecture\n\nHOKUSAI's architecture is built on a simple human-AI collaboration loop:\n\n- **Draft**: AI generates initial output based on specifications\n- **Review**: Human evaluates correctness, risk, and intent\n- **Fix**: AI refines output based on feedback\n- **Approve**: Human makes final decision\n- **Deploy**: Output is released or executed\n\nThis workflow ensures both speed and control.\n\n```mermaid\ngraph TD\n    A[Specification] --\u003e B[AI Draft]\n    B --\u003e C[Human Review]\n    C --\u003e D[AI Fix]\n    D --\u003e E[Human Approval]\n    E --\u003e F[Deployment]\n\n    C --\u003e|Feedback Loop| B\n```\n\n## Workflow\n\nHOKUSAI is built around a simple but powerful workflow:\n\n1. **Research** — Investigate the task scope and existing code\n2. **Design** — Plan the architecture and approach\n3. **Plan** — Build a step-by-step execution checklist\n4. **Implement** — Execute changes via an LLM-based coding agent (Claude Code by default)\n5. **Verify** — Run tests and lint to confirm correctness\n6. **Review** — Final review against quality checklists\n7. **Branch hygiene** — Confirm scope and base-branch consistency\n8. **PR draft → Unified review loop** — Create a draft PR and handle Copilot / human review comments in any order\n9. **Approval** — Human approves the PR for merge\n10. **Record** — Persist outcomes for traceability and audit\n\nEach phase can pause for human input. Humans approve transitions, request revisions, or override at any point — keeping responsibility clearly on the human side while AI handles execution.\n\n## Key Capabilities\n\n- **Human-in-the-loop control** — Humans approve transitions, request revisions, or override at any point\n- **Standardized workflow design** — Reusable, explicit phases replace ad-hoc AI usage\n- **Full traceability and auditability** — Every action is logged for review and compliance\n- **AI orchestration layer** — Multiple AI tools (Claude Code, Copilot, etc.) integrated through a single workflow\n- **Knowledge-driven execution (specification-first)** — Tasks start from a clear specification, not from prompt improvisation\n\n## Use Cases\n\nHOKUSAI is particularly suited for environments where control and accountability are critical:\n\n- **Financial systems and payment platforms**\n- **Enterprise software development**\n- **Compliance-heavy operations**\n- **Contract and document review workflows**\n\n## What HOKUSAI is NOT\n\n- **Not just an AI tool** — it's a structured workflow that uses AI\n- **Not just an agent system** — humans are first-class participants, not optional reviewers\n- **Not just a prompt collection** — prompts are part of a larger orchestrated process\n- **Not just a RAG pipeline** — knowledge integration is one component, not the whole system\n\nHOKUSAI is an **operational framework** for integrating AI into real-world workflows.\n\n## Design Principles\n\n- **Human-centered** — Humans remain responsible for decisions\n- **AI-accelerated** — AI improves speed and efficiency, not the other way around\n- **Workflow-driven** — Processes are explicitly defined and reusable\n- **Observable** — Every action is logged and traceable\n- **Scalable** — Designed for organizational adoption, not just individual use\n\n## Features\n\n### Standard\n\n- 10-phase LangGraph workflow (research → design → plan → implement → verify → review → branch hygiene → PR draft → unified review loop → record)\n- CLI commands: `start`, `continue`, `status`, `list`, `cleanup`, `pr-status`, `connect`, `notion-setup`, `notion-migrate-schema` (v0.4.8+), `profile`, `prime`, `dashboard`\n- Operations Console (`hokusai dashboard`) with service connection status, profile display, Basic Auth support, and retry/diagnostic panels\n- SQLite-based persistence and LangGraph checkpointing\n- LLM-based coding agent integration for autonomous implementation (Claude Code by default)\n- GitHub integration via the `gh` CLI\n- GitHub Issue task backend\n- Notion task backend and Notion dashboard sync with SQLite outbox-based retry\n- `hokusai notion-setup` for initial Notion workspace setup\n- Profile-based execution scopes for multiple projects/accounts (`--profile`, `hokusai profile list/show/doctor`)\n- Phase 7.5 branch hygiene checks (file scope, base-branch sync)\n- Figma / Miro design context integration, including read-only context extraction and optional writeback support\n- Customizable prompts in `prompts/`\n- `hokusai connect \u003cgithub|gitlab\u003e` / `hokusai connect --status` for guided CLI authentication and a quick connection-status read-out\n- Slack notifications (Incoming Webhook) for workflow start, human-review pauses, failures, PR creation, and completion\n- **`hokusai cleanup` workflow lifecycle** — `--cancel-reason \"\u003ctext\u003e\"` records a cancel reason on the Notion Workflows DB row; `--gc-workflows` (with `--retention-days N`, default 90) deletes completed workflows older than the retention window from `workflow.db`, cascading to `checkpoints` / `audit_logs` / `notion_sync_*` / `figma_sync_*` / `miro_sync_*` / `design_writeback_idempotency`. `cleanup --stale --dry-run` lists worktrees that would be removed without performing the delete (v0.5.0+), and `cleanup --stale --sync-notion` additionally cancels each removed workflow on the Notion Workflows DB to prevent ghost rows.\n- **LLM Gateway** — Phase 1 audit log-only by default. Every LLM call routes through `dispatch_via_gateway`, which records `provider` / `model` / `purpose` / `policy_hits` to SQLite `audit_logs` (prompt body is **never** stored; only hash + length). Opt-in Phase 2 enforcement via `llm_gateway.log_only=false` raises `LLMGatewayBlockedError` and aborts LLM execution when a call violates the configured `allowed_providers` / `allowed_models` policy. Gateway-internal failures (audit persistence errors, etc.) fall back open per the §4.4 fail-open principle, so a gateway bug never blocks the workflow — only explicit policy decisions do.\n\n### Experimental\n\nThe following components are present in the codebase but are not enabled by default. Behavior may change without notice.\n\n- **Multiple repositories** (mono-repo style) — single-repository setup is the default.\n- **Cross-LLM review** — opt-in via `cross_review.enabled`. Choose the reviewer LLM with `cross_review.provider` (`codex` for OpenAI Codex CLI, or `gemini` for Google Gemini CLI; v0.4.6+).\n- **Figma / Miro writeback** — disabled by default; enable per config and profile.\n- **Jira / Linear task backends and Bitbucket hosting** — interfaces exist but are unfinished.\n- **GitLab hosting** — client support exists, but the Phase 8 unified review loop is still GitHub-first.\n\n## Prerequisites\n\n- **Python**: 3.11 or later\n- **`gh` CLI**: authenticated with `repo` scope (required for PR management and review-comment handling)\n- **LLM-based coding agent CLI**: at least one installed and configured (e.g., Claude Code — used as the default driver for autonomous implementation)\n- **Git**: 2.30 or later\n\nThe Phase 8 unified review loop replies to PR review comments via `gh`, so the authenticated user must have write access to the target repository.\n\n## Installation\n\n```bash\n# Using uv (recommended)\nuv pip install hokusai-flow\n\n# Or using pip\npip install hokusai-flow\n```\n\n\u003e Note: the GitHub repository name is `hokusai`, but the PyPI distribution is `hokusai-flow` because `hokusai` on PyPI is held by an unrelated project.\n\n## Quick Start\n\n```bash\n# Start a new workflow from a GitHub issue URL\nhokusai -c configs/example-github-issue.yaml start https://github.com/your-org/your-repo/issues/1\n\n# List workflows\nhokusai list\n\n# Resume a workflow that paused for review\nhokusai continue \u003cworkflow-id\u003e\n\n# Inspect status\nhokusai status \u003cworkflow-id\u003e\n\n# Open the dashboard\nhokusai dashboard\n\n# Use a profile for a specific project/account\nhokusai --profile company-a start https://github.com/your-org/your-repo/issues/1\n\n# Inspect configured profiles\nhokusai profile list\n```\n\nState is stored under `~/.hokusai/` by default (`workflow.db`, `checkpoint.db`, `logs/`). Override with the `data_dir` config option if needed. For multi-project operation, use profiles to isolate `data_dir`, databases, worktrees, dashboard ports, and environment-variable names per project.\n\n## Configuration\n\nSee `configs/example-github-issue.yaml` and `configs/example-gitlab.yaml` for sample configurations. A minimal configuration looks like:\n\n```yaml\nproject_root: ~/repos/my-project\nbase_branch: main\n\ntask_backend:\n  type: github_issue\n\ngit_hosting:\n  type: github\n```\n\nFor profile-based operation, start from:\n\n- `configs/example-profiles.yaml` — profile registry **example** (illustrative, multi-project)\n- `configs/example-profile-company.yaml` — per-project configuration **example** (all fields)\n- `configs/profile-template.yaml` — profile registry **template** for team operations (v0.4.7+, copy-and-fill placeholders)\n- `configs/profile-config-template.yaml` — per-project configuration **template** (v0.4.7+, copy-and-fill placeholders)\n\n**New team member onboarding (using templates):**\n\n```bash\n# 1. Copy the registry template to your home directory\ncp configs/profile-template.yaml ~/.hokusai/profiles.yaml\nchmod 600 ~/.hokusai/profiles.yaml\n\n# 2. Copy the project config template to a shared directory\ncp configs/profile-config-template.yaml ~/work/hokusai-configs/\u003cprofile_name\u003e.yaml\nchmod 600 ~/work/hokusai-configs/\u003cprofile_name\u003e.yaml  # config also contains operational metadata (env var names, repo paths)\n\n# 3. Replace `\u003cTODO:...\u003e` placeholders (grep helps you find leftovers)\ngrep -n \"\u003cTODO:\" ~/.hokusai/profiles.yaml ~/work/hokusai-configs/\u003cprofile_name\u003e.yaml\n\n# 4. Set environment variables (API tokens, etc.) in your shell rc\n\n# 5. Verify with profile doctor\nhokusai --profile \u003cprofile_name\u003e profile doctor\n```\n\nThe `example-*` files are illustrative samples covering many use cases; the `*-template.yaml` files are ready-to-copy starting points with explicit `\u003cTODO:...\u003e` markers.\n\nCommon profile commands:\n\n```bash\nhokusai profile list\nhokusai profile show company-a\nhokusai profile doctor company-a\nhokusai --profile company-a dashboard\n```\n\nWhen neither `--profile` nor `-c/--config` is specified, HOKUSAI automatically resolves the registry's `default_profile` (v0.4.8+), so the default project's data is loaded consistently across every subcommand — `hokusai list`, `hokusai start`, `hokusai prime`, etc. The CLI prints `Profile: \u003cname\u003e (default_profile)` to distinguish implicit resolution from explicit `--profile` use. If the registry is missing or `default_profile` is unset, HOKUSAI silently falls back to the legacy `claude-workflow.yaml` search (no behavior change for users without a registry).\n\n### Notion dashboard setup (optional)\n\nHOKUSAI can create and sync a Notion operations dashboard through the Notion API. Token values are passed through environment variables, not YAML.\n\n```bash\nexport HOKUSAI_NOTION_API_TOKEN=\"secret_...\"\nhokusai notion-setup --parent-page-id \u003cnotion-page-id\u003e --persist\n```\n\nAfter setup, the generated database IDs can be referenced through environment variables such as `HOKUSAI_NOTION_WORKFLOWS_DB_ID`, `HOKUSAI_NOTION_PR_DB_ID`, `HOKUSAI_NOTION_REVIEW_ISSUES_DB_ID`, `HOKUSAI_NOTION_WORK_ITEMS_DB_ID`, `HOKUSAI_NOTION_WORKFLOW_GATES_DB_ID`, and `HOKUSAI_NOTION_PROJECT_MEMORY_DB_ID`.\n\nFor profile-based operation with multiple Notion workspaces, the env variable names can be customized per profile in the profile config (`notion_dashboard.api_token_env` / `workflows_db_id_env` / `pull_requests_db_id_env`). When `--profile \u003cname\u003e` is supplied to `notion-setup`, HOKUSAI automatically reads those env names from the profile config. With `--persist` enabled, HOKUSAI writes the resolved names to the rc file using a profile-tagged marker so that multiple profiles can coexist in the same rc file (without `--persist`, only the `export` example is printed to stdout):\n\n```bash\n# profile config defines HOKUSAI_NOTION_API_TOKEN_4HOKUSAI etc.\nhokusai --profile hokusai notion-setup --parent-page-id \u003cnotion-page-id\u003e --persist\n```\n\n#### Documentation tree scaffold (v0.4.3+, v0.4.5 updates titles)\n\nTo bootstrap a Notion governance layer with the recommended documentation tree alongside the DBs, pass `--scaffold`. The tree consists of a hub `Documentation` (icon 📚) with three child pages: `議論` (icon 💬), `運用ガイド` (icon 📖), and `要件定義` (icon 📋).\n\n```bash\nhokusai --profile hokusai notion-setup \\\n  --parent-page-id \u003cnotion-page-id\u003e \\\n  --scaffold \\\n  --persist\n```\n\nThe flag is opt-in. The scaffold step is idempotent on a **path-specific basis**: the hub page `Documentation` is looked up directly under the parent, and the three category pages are looked up under the hub. A page with the same title that exists at a different location (e.g. `議論` directly under the parent rather than under the hub) is **not** treated as existing and will not block creation. Note that the DB creation step is **not** idempotent: re-running `notion-setup` will create new `Workflows DB` / `Pull Requests DB` each time, so only re-run when you intend to provision a fresh DB pair (or archive the old DBs in Notion first).\n\n\u003e **v0.4.5 / Issue #29**: Dropped the `HOKUSAI` prefix from databases / hub page (the parent page typically provides the HOKUSAI context). Subpage titles are now Japanese (`議論` / `運用ガイド` / `要件定義`). Pages created by older versions are still detected on re-run via backward-compatible aliases for two generations: v0.4.3 (emoji-prefixed titles) and v0.4.4 (HOKUSAI-prefixed English titles). To align the UI with the new naming, rename the existing pages in Notion (the icon remains).\n\n### Figma / Miro integration (optional)\n\nFigma and Miro integrations can read design context into the workflow. Writeback for comments/cards is available behind explicit config flags.\n\n```yaml\nfigma:\n  enabled: true\n  api_token_env: HOKUSAI_FIGMA_API_TOKEN\n  writeback:\n    enabled: false\n\nmiro:\n  enabled: true\n  api_token_env: HOKUSAI_MIRO_API_TOKEN\n  writeback:\n    enabled: false\n```\n\nAPI tokens should be provided through environment variables. Do not store them in YAML.\n\n### Slack notifications (optional)\n\nHOKUSAI can post workflow events to a Slack Incoming Webhook. The webhook URL is **never** stored in YAML — pass it via an environment variable.\n\n```bash\nexport HOKUSAI_SLACK_WEBHOOK_URL=\"https://hooks.slack.com/services/T.../B.../...\"\n```\n\n```yaml\nnotifications:\n  slack:\n    enabled: true\n    webhook_url_env: HOKUSAI_SLACK_WEBHOOK_URL  # default\n    events:\n      - waiting_for_human\n      - workflow_failed\n      - pr_created\n      - workflow_completed\n    timeout: 5.0  # seconds, clamped to [1.0, 30.0]\n```\n\nSupported events: `workflow_started`, `waiting_for_human`, `workflow_failed`, `pr_created`, `workflow_completed`.\n\nIf sending fails (timeout, HTTP error, network error), the workflow continues running — notification failures never abort the workflow. The webhook URL is not written to logs or DB. Pasting the webhook URL directly into the YAML triggers a `Slack Incoming Webhook URL` warning in the dashboard.\n\n## Documentation\n\n- Implementation prompts: `prompts/`\n- Phase node sources: `hokusai/nodes/`\n- Configuration model: `hokusai/config/models.py`\n- Profile operation guide: `docs/profile-operation-guide.md`\n- Notion dashboard operation guide: `docs/notion-dashboard-operation-guide.md`\n- Figma / Miro operation guide: `docs/figma-miro-integration-operation-guide.md`\n\n## Limitations\n\n- The unified review loop in Phase 8 currently assumes GitHub-based pull requests. GitLab/Bitbucket support is experimental.\n- Profiles support multiple projects/accounts in parallel, but concurrent workflows for the same task URL within the same profile are not supported.\n- Prompts in `prompts/` are tuned for Japanese-language tasks; English-language tuning is under way.\n\n## License\n\nApache License 2.0. See [LICENSE](./LICENSE).\n\n## Contributing\n\nThis project is in alpha. Issues and pull requests are welcome — please open an issue first to discuss substantial changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshigenoko%2Fhokusai","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshigenoko%2Fhokusai","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshigenoko%2Fhokusai/lists"}