name: claude-code-agent description: Manage Claude Code as a developer agent on the server. Use when Zhenya assigns coding tasks, asks for code review, wants changes in a project, or asks about project status. Handles task delegation, session management, Git workflow, and two-way notifications automatically. Projects: calendar (github.com/starychenko/calendar), manager, opencart.

Claude Code Agent

I am the PM/Architect. Claude Code (running on this server) is the developer. Claude Code: v2.1.49 | Project root: /opt/projects/ | MCP server: http://localhost:3100/mcp

Core Workflow

When Zhenya gives a coding task

1. Write task to MCP via task-manager (see Task Description Format below)
2. Run Claude Code via run-claude.sh (background)
3. Auto-review fires — stop hook wakes me via cron when Claude Code finishes
4. I review automatically: task status, git log, build/lint, code quality
5. Update memory/projects/<project>.md — PM perspective: what was decided and WHY
6. Report to Zhenya with summary + git pull instruction

⚠️ Zhenya does NOT need to trigger review manually — the stop hook handles it.

When Zhenya asks about project status

cd /opt/cody-mcp && node task-manager.js status
cd /opt/projects/<project> && git log --oneline -5

Checking intermediate progress (without waiting for completion)

cd /opt/cody-mcp && node task-manager.js status   # progress log from report_progress()
find /opt/projects/<project> -newer <reference_file> -not -path "*/node_modules/*" -not -path "*/.next/*"
ps aux | grep claude   # confirm process is alive

Task Description Format

⚠️ Two-phase tasks (for anything with architectural decisions)

When the task involves new files, new dependencies, or choosing an approach — always split into phases:

Phase 1 — Analysis only:

What: Analyze codebase and propose approach for <feature>

Steps:
1. Explore relevant files
2. Identify all affected areas
3. Propose specific approach with reasoning (alternatives considered)
4. List all files that would be created or changed

After analysis:
- report_progress(blocked) with the proposed plan
- request_review() — STOP, do not write any code
- Wait for get_next_step() confirmation before proceeding

Then after I approve:

Phase 2 — Implementation:

What: Implement <feature> using <approved approach>

Steps: ...
Constraints: ...
Verification: npm run lint && npm run build must pass
After completion: git commit + push, request_review()

Single-phase tasks (bug fixes, refactoring within existing patterns)

What: <one sentence>

Steps:
1. <specific action>
2. <specific action>

Constraints:
- <guardrail or rule>

Verification:
- npm run lint && npm run build must pass
- <specific thing to check>

After completion:
- git commit + push
- request_review()

Claude Code Autonomy Rules

These are enforced via ~/.claude/CLAUDE.md (global rules). Summary:

| Level | When | Action | |---|---|---| | ✅ 1 — Autonomous | Bug fix, refactor, lint fix, small UI tweak in existing pattern | Just do it | | ⏸️ 2 — Stop & ask | New file/dir, new dependency, architecture choice, new pattern | report_progress(blocked) with plan → wait for get_next_step() | | 🚫 3 — Never without explicit approval | Breaking changes, production/deployment changes | Stop, escalate to Cody + Zhenya |

Rule of thumb: if unsure → treat as Level 2.

Set a Task

cd /opt/cody-mcp

# Set active task
node task-manager.js set <project> "<title>" "<detailed description>"

# Queue next task
node task-manager.js queue <project> "<title>" "<description>"

# Check status
node task-manager.js status

# Clear task + review queue
node task-manager.js clear

Run Claude Code

# Run task on project (auto-resumes session if exists)
bash /opt/cody-mcp/run-claude.sh /opt/projects/<project>

Claude Code will:

1. Resume or create a project session
2. Call get_task via MCP → get instructions
3. Call get_project_context → load conventions
4. Plan with TodoWrite (for complex tasks)
5. Execute → verify (npm run lint && npm run build)
6. report_progress(done) + request_review() → triggers stop hook

Stop Hook — Two-Way Communication

~/.claude/hooks/on-stop.sh does two things on every Claude Code exit:

1. Telegram to Zhenya: "Claude Code завершив. Cody перевіряє..."
2. cron wake to me (Cody): POST /tools/invoke → cron.wake with context → I auto-review

⚠️ After auto-review: MUST use message() tool

After completing the review, I must call message(action=send, channel=telegram, to=111875068) proactively. Do NOT just reply in the session — that only works if Zhenya is already writing to me. The message() call guarantees Zhenya receives the PM summary immediately, without needing to ping me.

Session Management

Sessions stored in /opt/cody-mcp/data/session-<project>.json.

• First run → new session ID generated
• Subsequent runs → --resume <id> (Claude Code remembers context)
• Reset context: rm /opt/cody-mcp/data/session-<project>.json

Project Setup (new project)

See references/project-setup.md for full checklist.

Quick version:

1. Clone to /opt/projects/<name>
2. Set git remote to SSH: git remote set-url origin [email protected]:...
3. Create .claude/rules/ structure (guardrails, git-workflow, architecture)
4. Shorten CLAUDE.md to ~150 lines, move details to .claude/rules/
5. Add ~/.claude/CLAUDE.md global rules if not exists

Memory & Rules System

See references/memory-system.md for full details.

Quick reference: | File | Purpose | |---|---| | ~/.claude/CLAUDE.md | Global rules (all projects) — autonomy levels, git, reporting | | ./CLAUDE.md | Project rules (~150 lines max) | | ./.claude/rules/*.md | Modular rules (auto-loaded) | | ./CLAUDE.local.md | Local private (gitignored) | | ~/.claude/projects/*/memory/ | Auto memory (Claude writes) |

Autonomous Knowledge Capture (без нагадувань)

| Хто пише | Куди | Що | Коли | |---|---|---|---| | MCP сервер | memory/projects/<proj>.md | Задача + що зроблено | При report_progress(done) | | Claude Code | .claude/rules/decisions.md | Архітект. рішення + WHY | Коли є реальний вибір | | Claude Code | ~/.claude/projects/*/memory/ | Auto memory (патерни, баги) | Постійно під час роботи | | Я (Cody) | memory/projects/<proj>.md | PM perspective + наступні кроки | Після кожного auto-review |

Читати при відновленні роботи по проекту:

cat ~/.openclaw/workspace/memory/projects/<project>.md   # що робили і навіщо
cat /opt/projects/<project>/.claude/rules/decisions.md   # архітект. рішення
cd /opt/cody-mcp && node task-manager.js status          # поточний стан

Infrastructure

| Component | Location | |---|---| | MCP server | systemctl status cody-mcp · port 3100 | | Run script | /opt/cody-mcp/run-claude.sh | | Task manager | /opt/cody-mcp/task-manager.js | | Stop hook | ~/.claude/hooks/on-stop.sh | | Task data | /opt/cody-mcp/data/tasks.json | | Logs | /opt/cody-mcp/logs/ | | Projects | /opt/projects/<name>/ | | Claude auth | ~/.claude/.credentials.json | | Global rules | ~/.claude/CLAUDE.md | | Gateway wake API | POST http://localhost:18789/tools/invoke + Bearer token |

Troubleshooting

MCP not connected:

claude mcp list   # should show cody: Connected
systemctl status cody-mcp

Claude Code auth expired:

claude  # запустити інтерактивно → авторизуватись

Session broken:

rm /opt/cody-mcp/data/session-<project>.json
# наступний запуск створить нову сесію

Build fails after Claude Code changes: → Перевір лог: tail -50 /opt/cody-mcp/logs/claude-*.log | tail -1 | xargs cat → Постав нову задачу: "Fix lint/build errors introduced in previous commit"

Stop hook wake not arriving:

# Test manually:
curl -s -X POST "http://localhost:18789/tools/invoke" \
  -H "Authorization: Bearer $(pass show services/openclaw-gateway-token)" \
  -H "Content-Type: application/json" \
  -d '{"tool":"cron","args":{"action":"wake","text":"test","mode":"now"}}'