Code Agent Octopus 🐙

A centralized toolkit for AI coding assistants, providing reusable agents, commands, and workflows that work across multiple CLIs.

Purpose

• Provide production-ready agents, commands, and MCP-aware workflows for AI coding assistants
• Support Claude Code, Codex CLI, Factory CLI, and GitHub Copilot CLI
• Ship factory templates (.factory/) alongside active configurations so teams can bootstrap new projects quickly
• Document best practices for managing sub-agents, hooks, and automation around Context7-driven development

Supported CLIs

CLI	Configuration	Location
Claude Code	Sub-agents + commands + skills	.claude/
Codex CLI	AGENTS.md + commands + skills	.codex/
Factory CLI	AGENTS.md + droids + skills	.factory/
OpenCode CLI	Agents + commands + skills	.opencode/
Copilot CLI	AGENTS.md + prompts + skills	.github/

Repository Map

code-agent-octopus/
├── AGENTS.md                  # Vendor-neutral config (Codex, Factory, Copilot)
├── CLAUDE.md                  # Claude Code specific guidance
├── .claude/
│   ├── agents/                # Claude Code sub-agents
│   ├── commands/              # Slash commands (Context7-enabled)
│   └── skills/                # Skills with shell scripts (automation)
├── .codex/
│   ├── commands/              # Codex CLI command mirrors
│   └── skills/                # Codex CLI skills (worktree, etc.)
├── .factory/
│   ├── droids/                # Canonical agent templates (source of truth)
│   ├── commands/              # Canonical command templates
│   └── skills/                # Factory CLI skills (worktree, etc.)
├── .opencode/
│   ├── agent/                 # OpenCode CLI agents (flat structure)
│   ├── command/               # OpenCode CLI commands (flat structure)
│   └── skills/                # OpenCode CLI skills (worktree, etc.)
├── .github/
│   ├── prompts/               # GitHub Actions/Copilot prompts
│   └── skills/                # GitHub Copilot CLI skills (worktree, etc.)
└── docs/
    └── claude-code/           # Guides for commands, agents, hooks

Key Components

• Planning Agents (.factory/droids/planning-agents/*.md, .claude/agents/planning-agents/*.md)
  Architecture, testing, deployment, and quality advisors designed to delegate long-form reasoning tasks while staying within Context7 guardrails.
• Code Review Agents (.factory/droids/code-review-agents/*.md)
  Security, performance, testing, and bug-finding specialists that rely on Context7 lookups for framework-specific guidance.
• Research & Memory Commands (.factory/commands/research/*.md, .factory/commands/context-memory/*.md)
  Provide repeatable flows for consulting Context7, capturing findings, and replaying project memory.
• Testing & Tooling Hooks (.factory/commands/testing/*.md, .claude/commands/testing/*.md) Automate Playwright, Chrome DevTools MCP, and quality checks across both CLIs.
• Skills (.claude/skills/) Shell script-based automation invoked via /skill-name. Skills execute scripts directly without model invocation, ideal for deterministic operations like git worktree management.

Skills vs Commands vs Agents

Type	Location	Invocation	Model	Use Case
Agents	.claude/agents/	Task(subagent_type="X")	Yes	Complex reasoning, analysis
Commands	.claude/commands/	/namespace:command	Yes	Guided workflows
Skills	.claude/skills/	/skill-name	No	Deterministic scripts

Key Difference: Skills use disable-model-invocation: true to run scripts directly.

Working With Templates

.factory/ contains canonical templates that sync to CLI-specific directories:

# Sync to Claude Code
cp -r .factory/droids/* .claude/agents/
cp -r .factory/commands/* .claude/commands/

# Sync to Codex CLI
cp -r .factory/commands/* .codex/commands/

Workflow:

1. Edit in Factory – Make changes to canonical templates in .factory/
2. Sync to CLIs – Copy to CLI-specific directories (.claude/, .codex/, etc.)
3. Validate – Test in your target CLI
4. Contribute Back – Update .factory/ when changes prove useful

Quick Start

Claude Code

claude
/agents                        # List sub-agents
/planning:agentic-jira-task-analyze PROJ-123
/worktree                      # Create git worktree with config sync

Codex CLI

codex
# AGENTS.md auto-loads project context
/worktree                      # Create git worktree with config sync

Factory CLI

factory droid code
# AGENTS.md auto-loads, droids available
/worktree                      # Create git worktree with config sync

OpenCode CLI

opencode
@planning-implementation       # Invoke agent with @mention
/worktree                      # Create git worktree with config sync

Copilot CLI

gh copilot   # Reads AGENTS.md and .github/copilot-instructions.md
/worktree                      # Create git worktree with config sync

Documentation

Project Docs

• CLAUDE.md – Comprehensive guide for Claude Code (architecture, agents, workflows)
• AGENTS.md – Vendor-neutral config for Codex, Factory, and Copilot CLIs
• Custom Slash Commands – Patterns for reusable workflows
• Sub-Agents Guide – Designing specialized assistants
• Hooks Guide – Event-driven automation
• Skills (Official Docs) – Shell script automation

Official References

• Claude Code · Codex CLI · Factory CLI · Copilot CLI
• Model Context Protocol · Context7

Security Notes

• Agents and hooks execute with the same permissions as your CLI session; review YAML frontmatter and tool scopes before enabling them.
• Keep sensitive credentials out of version control—store them in .claude/settings.local.json or environment-specific vaults.
• Follow principle of least privilege when enabling MCP servers (Playwright, GitHub, etc.).