claude-factory

A personal "loop engineering" system driven by voice conversation.

When you speak to it in voice mode in the Claude app, the Claude Code behind it works on the repository, and when a decision is needed, it asks you a question. Answer by voice or on screen and the work continues. The concept is in docs/01_企画書.md, the implementation policy in docs/02_制作指示書.md, and session management in docs/03_セッション管理.md.

あなた（音声）
  └ Claude アプリ／ボイスモード（秘書）
      └ カスタムコネクタ = MCP Bridge Server（Bearer 認証）
          ├ Orchestrator ── Claude Code（claude-agent-sdk）── 各リポジトリ
          └ SQLite ── Dashboard（FastAPI + React）

At the core is a plan → approval → execution gate. Any work that involves writes always comes back as a plan first and is not executed until you approve it.

1. Setup

Python 3.12+, Node.js 18+, Claude Code CLI (logged in with a Max account).

# Mac / Linux
uv sync --extra dev              # または: pip install -r requirements.txt
cp .env.example .env
python -c "import secrets; print(secrets.token_urlsafe(32))"   # → .env の CF_MCP_TOKEN
python -c "import secrets; print(secrets.token_urlsafe(16))"   # → .env の CF_DASHBOARD_PASSWORD

# Windows
python -m venv .venv; .\.venv\Scripts\Activate.ps1
pip install -r requirements.txt
copy .env.example .env    # 中身のトークンを実値に置き換える

Because the SDK takes over Claude Code authentication, launch claude once on the host where it will run and log in with your Max account.

Adjust config.yaml to your environment

At minimum, change the directories you are allowed to touch. All paths not listed here are rejected.

security:
  repo_allowlist:
    - ~/Private_Project           # Mac
    # - C:\Users\<you>\repos      # Windows

Related MCP server: MCP-Claude Code Bridge

2. Startup

./scripts/run_mcp.sh          # MCP サーバー（秘書の窓口 + ジョブのワーカー）
./scripts/run_dashboard.sh    # ダッシュボード（初回はフロントも自動ビルド）

.\scripts\run_mcp.ps1
.\scripts\run_dashboard.ps1

• MCP: http://127.0.0.1:8010/mcp

• Dashboard: http://127.0.0.1:8787

It is the MCP server process that actually runs jobs. Even if only the dashboard is started, the queue does not advance. The one to run continuously is run_mcp.

Connectivity check:

curl -i http://127.0.0.1:8010/mcp                    # 401 = 認証が効いている
curl -s -X POST http://127.0.0.1:8010/mcp \
  -H "Authorization: Bearer $CF_MCP_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

3. Register as a connector

./scripts/tunnel.sh quick     # 使い捨て（URL は起動ごとに変わる）

Take the displayed https://<ランダム>.trycloudflare.com, append /mcp, and paste it into the Claude app under "+" → Connectors → Add custom connector.

There are two ways to pass the token:

The path method leaks more easily because the token appears in the URL (it remains in logs). If you can use headers, set mcp.allow_path_token to false in config.yaml to block it off.

4. Usage

Speak to the secretary (voice) like this, for example:

Check the situation

• "What's the current status?" → get_org_status (the whole organization in one shot. Start here)

• "What about that job?" → get_job (switch summary / report / log with detail)

• "Read the investigation results" → read_board (all deliverables from the departments appear here)

Move the organization (heaviest first)

• "Start a new task with 'invoice parser'" → create_task (creates the directory + git init + registration in one step. No need to edit config.yaml or restart)

• "Ask the design team how to handle the storage method" → start_council (no files are changed, so you can use it freely)

• "What was the meeting conclusion?" → get_council (conclusion, discussion by disputed issue, and remaining objections)

• "Ask demo to fix the test failures" → dispatch_to_code (only a plan is created)

• "Approve it" → answer_question (only now is it executed)

• "I'll leave it to you with this goal" → grant_mandate (autonomous operation begins. Stop it with revoke_mandate)

Sessions

• "Fork the current session and try a different approach" → fork_session (isolated with a git worktree)

Organization structure (design document docs/04_組織化設計書.md)

子会社 = プロジェクト（互いに不干渉）
  部署 = 役割        調査 / 設計班 / 実装 / デザイン / 統合管理
    成果ボード       部署はここだけを介して成果を見せ合う

Design team meetings proceed through four chair-led stages.

1. Pre-reading — the chair settles obvious points on their own (recorded in resolved_by_chair) and extracts only the disputed issues

2. Referral — for each disputed issue, names people from the employee roster (with reasons)

3. Deliberation — the named people give opinions and critiques of earlier opinions

4. Conclusion — the chair gives conclusions for each disputed issue, remaining objections, and points for the human

The roster is config/personas.yaml (1 chair + 10 members). You can edit it freely, and it takes effect at startup.

Permissions by department (least privilege)

Research can see the Web but cannot write files; implementation can write files but cannot see the Web. Changes are made under roles: in config.yaml, and only humans can change it (no path is created for the orchestration agent to expand its own privileges).

Autonomous operation (mandate)

When you approve each goal with grant_mandate, the orchestrator hands out work to each department and proceeds without individual approvals. In exchange for fewer approvals, it is run in a form that can be discarded at any time.

• Creates a dedicated working branch (does not let it touch main)

• Attaches a budget (number of jobs/cost) and deadline, and stops automatically when exhausted

• Deletion, git push, history rewriting, and adding dependencies are outside the mandate. It always stops and confirms

• You can cancel everything, including running work, with the "Stop" button on the dashboard (revoke_mandate)

The dashboard shows the pending-question queue, progress timeline, live logs, reports, session fork tree, and audit log. Answers go through the same path whether by voice or on screen.

Secretary skills (skills/)

Because the operating practice is to start a new chat every morning, the secretary has no memory of the previous day. The startup procedure is provided as a skill in skills/factory-startup/ (situation gathering → reading order → today's proposal, with a read-aloud script).

Upload it from the Claude app settings and invoke it by typing /factory-startup (shorthand /cf) at the start of a chat. No natural-language trigger words are set (to avoid false positives and missed startups). The app's / suggestions come from the skill's name, so the name itself is the signal. See skills/README.md for details.

The roles are split between the connector-side SECRETARY_GUIDE (it rides on every request, so keep it short) and the skill (read only when needed, so it stores procedures and scripts).

Instructions that work for the secretary (Concept §Verification 4)

To keep it from sending requests on its own in the middle of a conversation, tell the secretary something like this:

Don't call dispatch_to_code until I say "submit the request with this." Until then, keep discussing it with me and help refine the instruction text.

5. Security (Implementation Specification §8)

Implemented defenses:

There are two important cautions we found by testing with real Claude Code, and countermeasures are in place:

• can_use_tool is not called for tools the CLI auto-approves. If you rely only on the authorization callback, writes outside the repository can happen even in plan mode. CLI-level prohibition via disallowed_tools and an OS sandbox (orchestrator.sandbox) are layered on top.

• Directory escapes via cd are not stopped by path checks. Absolute paths and .. in Bash commands are inspected with _bash_escapes_workspace.

The target repository's .claude/settings.json is not loaded (setting_sources=[]). If it were loaded, the repository could self-approve its own permissions.

6. Permanent public exposure (M5)

The disposable tunnel gets a different URL on every launch, so move to a named one if you plan to use it regularly.

cloudflared tunnel login
cloudflared tunnel create claude-factory
cloudflared tunnel route dns claude-factory mcp.<domain>
cloudflared tunnel route dns claude-factory dash.<domain>

~/.cloudflared/config.yml:

tunnel: claude-factory
credentials-file: /path/to/<tunnel-id>.json
ingress:
  - hostname: mcp.<domain>
    service: http://localhost:8010
  - hostname: dash.<domain>
    service: http://localhost:8787
  - service: http_status:404

Always-on exposure is handled by the systemd cloudflared.service (which reads /etc/cloudflared/config.yml).

systemctl status cloudflared          # 状態確認
sudo systemctl restart cloudflared    # 設定変更の反映
journalctl -u cloudflared -f          # ログ

You can also start it with ./scripts/tunnel.sh named claude-factory, but it is usually not used because a connector is duplicated onto the same tunnel as the resident service. If you switch to manual operation, run sudo systemctl stop cloudflared first. The script also detects the resident service, warns you, and asks for confirmation.

On the Route 53 side, cloudflared tunnel route dns creates a CNAME (<tunnel-id>.cfargotunnel.com). The connector registration URL is https://mcp.<domain>/mcp. Put Cloudflare Access in front of the dashboard, and set dashboard.auth: none only in that case.

7. Development

.venv/bin/python -m pytest -q                                  # テスト
cd src/claude_factory/dashboard/web && npm run dev             # フロントの開発サーバー

The structure corresponds to Implementation Specification §2 (it is placed in the src/claude_factory/ package rather than directly under src/):

src/claude_factory/
├─ config.py        設定（config.yaml + .env）
├─ models.py        型・出力規約・その解析
├─ store.py         SQLite DAO
├─ security.py      トークン・allowlist・レート制限
├─ runner.py        claude-agent-sdk ラッパと承認ゲート（役割別の権限）
├─ orchestrator.py  ジョブキュー、計画→承認→実行、自走ループ
├─ sessions.py      セッション一覧/閲覧/分岐（git worktree 隔離）
├─ personas.py      社員名簿と組閣
├─ council.py       設計班の合議エンジン
├─ integrate.py     統合管理（作業計画を出すだけ。実行はしない）
├─ org.py           組織全体の状況
├─ mcp_server.py    秘書向け MCP
└─ dashboard/       FastAPI + React(Vite)

Documentation: docs/01_企画書.md (concept) → 02_制作指示書.md (foundation) → 03_セッション管理.md (supplement) → 04_組織化設計書.md (organization).

8. Remaining items

• M6 voice E2E: run one real project with voice only (verify manually after connector registration).

• Push notifications for pending decisions (v2).

• Cleanup rules for forked worktrees (delete or keep after merge).

• Detection when the orchestrator keeps assigning the same work (currently the budget and deadline are the only brake).

• Whether the mediator should be the orchestrator or escalated to a human when departments disagree.