メニュー
Run and monitor samocode autonomous sessions on projects. Use when user says "run samocode" or wants to continue a samocode session.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/Yuvasee/samocode --skill samocode-runコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
SKILL.md を表示中
SOC 職業分類に基づく
Execute implementation tasks with different approaches (single, dual-agent, plan-based).
Code quality analysis through cleanup analysis, multi-perspective reviews, and explicit finding decisions.
Interactive task definition with Q&A and documentation.
| name | samocode-run |
| description | Run and monitor samocode autonomous sessions on projects. Use when user says "run samocode" or wants to continue a samocode session. |
Runs the samocode autonomous orchestrator on a project session and monitors its progress.
When user asks to "run samocode" or "continue samocode", you MUST use this skill.
DO NOT:
_overview.md and decide what phase to run_signal.json yourselfThe Python worker (main.py) handles ALL of this. Your job is to START the worker and MONITOR its output.
Use this skill when user says:
/samocode-implementSamocode is an autonomous session orchestrator that runs the configured AI CLI provider in a loop to complete complex tasks. It:
_overview.mdFor workflow details and phase definitions, see ~/samocode/CLAUDE.md.
There's no strict "samocode session" - just sessions. Any session can be worked on:
This flexibility is intentional. Use samocode for repetitive/long-running phases, work manually when human judgment is needed.
Only when user explicitly asks for samocode (see Trigger Phrases above).
Do NOT assume samocode should run just because a session exists.
Arguments: $ARGUMENTS (session name or project path with session name)
Find .samocode config:
.samocode file in current working dir or project path.samocode file (e.g., ~/project/.samocode).samocode file is missing: ERROR and ask user to create itDetermine session name:
$ARGUMENTS is a session name (e.g., "my-task"), use it directly$ARGUMENTS includes a path, extract session name from itCheck session state (if exists):
_overview.md Status section/samocode-implement equivalent:
Phase: planning and the session is waiting for plan approval (Blocked: waiting_human, Next: Await plan approval, or _signal.json has waiting_for: plan_approval / "for": "plan_approval"), approve the gate before starting samocode:
Phase: implementationBlocked: noLast Action: Plan approved for implementationNext: Execute first implementation phase- [MM-DD HH:MM] Plan approved for implementation via samocode-runPhase: done:
_overview.md:
Phase: investigationLast Action: Resuming session for: [user's goal]Next: Investigate approach for [user's goal]When samocode signals waiting:
Auto-approve/answer ONLY if user explicitly requested it (e.g., "run samocode and approve", "accept suggestions", "auto-approve"). Otherwise, report the waiting state and wait for user decision.
For waiting_for: plan_approval:
_overview.md (NOT _signal.json):
Phase: implementationBlocked: noLast Action: Plan approved by humanFor waiting_for: qa_answers:
_qa.md with answersCRITICAL: Update _overview.md, not _signal.json
The orchestrator reads phase from _overview.md. Writing to _signal.json alone will cause loops.
.samocode FileEvery project using samocode MUST have a .samocode file in its root:
MAIN_REPO=~/path/to/main/repo
WORKTREES=~/path/to/worktrees/
SESSIONS=~/path/to/_sessions/
All three keys are REQUIRED:
MAIN_REPO: The main working directory (where the child agent runs)SESSIONS: Where samocode session folders are storedWORKTREES: Where git worktrees are createdSessions are stored in SESSIONS dir (from .samocode file), NOT nested inside projects:
[SESSIONS_DIR]/
└── [YY-MM-DD]-[session-name]/ # Session folder (e.g., 26-01-15-pyright-ci)
├── _overview.md # Main session state
├── _signal.json # Control signal
├── _qa.md # Q&A when waiting for human input
├── _logs/ # Agent iteration logs (JSONL)
│ └── [MM-DD-HHMM]-[NNN]-[phase].jsonl
├── [MM-DD-HH:mm]-plan-*.md # Implementation plans
├── [MM-DD-HH:mm]-dive-*.md # Investigation reports
└── [MM-DD-HH:mm]-*.md # Other artifacts
## Status
Phase: [investigation|planning|implementation|testing|quality|done]
Iteration: N
Blocked: [yes/no]
Last Action: [what happened]
Next: [what to do next]
## Flow Log
- [NNN @ MM-DD HH:MM] Event description -> optional-file.md
.samocode file in project root with SESSIONS, WORKTREES, MAIN_REPO~/samocode/.env has TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_IDCLAUDE_TIMEOUT or CODEX_TIMEOUT) if iterations need moreIf samocode exhibits bugs or weird behavior (loops, wrong decisions, missing steps, etc.):
Analyze the issue:
_overview.md to see what went wrongSuggest fixes - DO NOT auto-implement:
Samocode source locations:
~/samocode/main.py, ~/samocode/worker/~/samocode/workflow.md~/samocode/skills/*/SKILL.md~/samocode/commands/*.mdCommon fix patterns:
IMPORTANT: Always propose fixes and wait for user approval. Samocode is critical infrastructure - no cowboy coding.
User: "Run samocode on the hvac project"
→ Find ~/code/hvac-voice-agent/.samocode file
→ Determine session name from context (e.g., "voice-agent")
→ Run: python main.py --config ~/code/hvac-voice-agent/.samocode --session voice-agent
→ Monitor iterations, report progress
User: "Continue the samocode session"
→ Find session name from context or ask user
→ Find .samocode file path
→ Run: python main.py --config [CONFIG_PATH] --session [SESSION_NAME]
→ Monitor iterations, report progress
Remember: You run python main.py, the Python worker runs the configured provider (Claude or Codex). You do NOT run phase agents yourself.
- [MM-DD HH:MM] Resuming: [user's goal]Blocked: yes or blocked:
Start samocode:
cd ~/samocode && python main.py \
--config [PATH_TO_.SAMOCODE] \
--session [SESSION_NAME] 2>&1
Optional: Add --timeout SECONDS for per-iteration time limit (default: 1800s = 30 min).
Each child agent iteration is killed if it exceeds this. Increase for complex phases:
python main.py --config ... --session ... --timeout 3600 # 1 hour per iteration
Do NOT wrap with bash timeout - The orchestrator manages its own timeouts via --timeout.
External timeouts can kill iterations mid-work and corrupt session state.
Run this in background using run_in_background: true
Avoid reading background task output directly. The samocode worker output includes full
Agent CLI logs which are large (100KB+ per iteration). Monitor progress via _overview.md
and other session files instead.
If debugging requires checking task output (e.g., investigating a crash):
grep to search for specific errors or patterns firsttail -n 2 or tail -n 5 max - each line can be huge (full JSON)Read with offset and limit to read small portionsMonitor loop (prefer session files over task output):
5.1. Start background check (sleep duration by phase: investigation/planning 60s, implementation 120-180s, quality 120s, testing 60s):
Bash(command="sleep 60 && cat [SESSION]/_overview.md", run_in_background=true)
Returns task_id (e.g., "b155903")
5.2. Wait for result - DO NOT SKIP, do immediately after 5.1:
TaskOutput(task_id="b155903", block=true, timeout=600000)
Note: 600000ms (10 min) is the max allowed timeout.
5.3. Extract from result: Phase, Iteration, Total Iterations, Blocked, Last Action, Next, last 3 Flow Log entries
5.4. Get recent commits:
git -C [WORKING_DIR] log --oneline -3
5.5. Report to user:
Samocode Progress [HH:MM elapsed]
--------------------------------
Phase: [phase] (Iteration N/Total)
Last: [Last Action]
Next: [Next]
Recent commits:
- [hash] [message]
Flow:
- [last 2-3 Flow Log entries]
5.6. Check stop condition:
Phase: done → report final summary, STOPBlocked: contains yes or waiting → handle accordingly (see Handling Waiting States), STOPIMPORTANT: On STOP, clean up monitoring. When samocode finishes (done/blocked/waiting), do NOT leave pending background sleep tasks running. Stop any active monitoring task via TaskStop before reporting the final status. This prevents stale notification floods.