convez.ai
AgenteAutomaçãoAvançado
nhangen

Claude CEO Agent

nhangen/claude-ceo

CEO autônomo que prioriza, delega e aprova trabalho a partir do seu vault

Ver no GitHub
InicialPluginScore · de 0 a 100

Agent autônomo que lê seu vault Obsidian, prioriza trabalho, delega tarefas para subagents especializados e aprende com correções. Executa playbooks agendados e controla escrita por tier de autoridade, permitindo que operadores solo gerenciem múltiplos domínios sem sobrecarga decisória.

Instalação

$npx convez-ai nhangen/claude-ceo

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
3
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 2 dias
Versão
v0.12.0
Issues abertas
39
Contribuidores
2

Casos de uso

  • Automação de fluxos de trabalho diários com priorização inteligente
  • Delegação de tarefas para subagents especializados (análise, code review, implementação, ops, pesquisa, escrita)
  • Execução de playbooks agendados com diferentes níveis de autoridade (read, low-stakes write, high-stakes approval)

Veredito

Ferramenta poderosa para operadores solo que precisam gerenciar múltiplos domínios com rigor operacional. Requer setup cuidadoso do vault Obsidian e compreensão de arquitetura de agents, mas entrega automação de decisões com salvaguardas appropriadas.

README

A tradução para o português deste README ainda está na fila.

claude-ceo

Autonomous CEO agent for Claude Code. Reads your Obsidian vault, dispatches specialized subagents, runs scheduled playbooks, and gates writes by authority tier.

Why

A solo operator has more domains than hours: code repos, research, ops, career, personal. Day-to-day, most of the work isn't doing — it's deciding what to do next, where you left off, and what's safe to ship without you. claude-ceo reads your Obsidian vault (the source of truth), runs prioritized scans on a cron schedule, and proposes work in tiers: read-only digests run automatically, low-stakes writes execute with a report, high-stakes actions queue for approval.

How it works

Cron / interactive trigger
  │
  ▼
ceo-cron.sh ──► ceo-config.sh        (resolve $CEO_VAULT)
            ──► ceo-gather.sh         (pre-gather context → env)
            ──► ceo-scan.sh           (vault diff)
            ──► registry.json         (dispatch lookup)
            ──► preflight_<name>()
            ──► runner:
                 • claude (default)   — read tier = single call,
                                        write tiers = PLAN/FILTER/EXECUTE
                 • script              — deterministic shell, no LLM
            ──► ceo-report.sh         (flock-guarded append)

Output: CEO/reports/YYYY-MM-DD.md
State:  CEO/log/, CEO/approvals/, CEO/cache/

Playbooks self-register: ceo playbook scan walks CEO/playbooks/*.md, extracts each frontmatter block via yq, rewrites registry.json, and updates the crontab between # CEO Agent START/END markers.

Subagents

Skills under skills/ceo/agents/ define six specialized subagents the CEO can dispatch for domain-specific work. Each declares its authority and domain scope; high-stakes actions (push, publish, send) are always returned as drafts.

SubagentAuthorityDomainsUse for
analystread + reportsCareer, Academics, allEvaluating options, thesis planning, cost-benefit, tool comparison
code-reviewerread + draft (post is high-stakes)Awesome Motive, any code repoPR review — diff analysis, CI check, draft comments
implementerread + low-stakes writeAwesome Motive, any code repoBug fix — branch, commit, test; push/PR returned as recommendation
ops-managerread + low-stakes writeNRX ResearchInventory, hiring pipeline, SOP execution, runbook compliance
researcherread onlyAcademics, Career, NRX Research, anyVault / web / claude-mem / academic source investigation
writerread + draftCareer, Academics, NRX Research, PersonalLinkedIn posts, cover letters, emails, academic writing, docs

Playbooks

Active playbooks shipped with the plugin (live in docs/playbooks/; copy into $CEO_VAULT/CEO/playbooks/ to enable, then ceo playbook scan):

PlaybookTriggerTierRunnerPurpose
morning-brief50 8 * * 1-5readclaudePrioritized day overview — PR queue, top-3 tasks, blessings
morning-scan57 8 * * 1-5readclaudeVault-diff digest of overnight changes
inboxevery 15 minreadclaudeProcess unchecked items in CEO/inbox.md and CEO/inbox/<host>.md (preflight-gated)
pr-triage03 10 * * 1-5readclaudeSurface PRs needing review
pending-dripdailyreadclaudeDrip reminders from Pending.md into CEO/inbox/<host>.md
eod-summary47 17 * * 1-5readclaudeRecap if there are log entries after 4pm
cleanupweeklylow-stakes-writeclaudeBranch / worktree hygiene
token-intake45 8 * * 1-5readscriptRun ceo-token-intake.sh — token-scope snapshot to vault

tier: read runs a single claude --print --max-turns 5 --disallowedTools Bash,Write,Edit call with pre-gathered context injected as <external-data> blocks. tier: low-stakes-write and above use the three-phase PLAN → FILTER → EXECUTE pipeline; high-stakes actions are written to CEO/approvals/pending.md instead of executed.

A playbook can declare runner: script to dispatch a shell script directly, skipping the LLM call entirely (token-intake is the canonical example). The script receives CEO_VAULT, CEO_DIR, LOG_DIR, TODAY, NOW, TRIGGER as env vars; the dispatcher does not parse stdout. Exit code 0 = success.

A playbook can also declare bin: <script>.sh in frontmatter to expose itself as a shell command: ceo playbook scan creates a ~/.local/bin/<name> symlink to that script and removes stale ones when the playbook is deleted or set inactive. ceo doctor warns when a declared bin symlink is missing.

Examples

Interactive triage from a Claude Code session:

/ceo

Reads today's report, walks the vault, and proposes prioritized actions in tier order.

Trigger a playbook by hand (no cron wait):

ceo cron morning-brief
ceo chat pr-triage          # same playbook, interactive instead of cron

Preview what the next cron tick would actually do:

$ ceo preflight
morning-brief    RUN     (read)
inbox            SKIP    (no unchecked items)
pr-triage        RUN     (3 reviews requested)

Read the day's report:

ceo chat                    # opens conversation about today's report
CEO_CHAT_EFFORT=high ceo chat # override chat effort (default: medium)
# or directly:
$EDITOR ~/Documents/Obsidian/CEO/reports/$(date +%F).md

Inspect a registered playbook:

ceo playbook list
ceo playbook info token-intake

Install

  1. Clone somewhere persistent (e.g. ~/ML-AI/claude/ceo).
  2. Run scripts/ceo setup — installs deps where it can, walks you through git/ssh/cron, creates ~/.ceo/config with the resolved vault path.
  3. Symlink the CLIs onto PATH:
    ln -s "$(pwd)/scripts/ceo"               ~/bin/ceo
    ln -s "$(pwd)/scripts/count-blessings.sh" ~/bin/count-blessings
    
  4. Run scripts/ceo doctor to verify everything resolves (yq, gh auth, vault, cron).
  5. Run ceo playbook scan to build registry.json and install the crontab.

Requirements

  • Obsidian vault synced across all machines
  • Syncthing running on every machine (no installer ships with this plugin)
  • claude-obsidian-plugin v1.4.0+ with VAULT.md and Profile.md in the vault root
  • gh CLI authenticated, jq, yq (install)
  • Claude Code with subscription (claude --print)

Syncthing

PlatformInstall
macOSbrew install syncthing && brew services start syncthing
WSL/LinuxAPT repo, then sudo apt install syncthing
WindowsInstaller or choco install syncthing

Open http://localhost:8384 on each machine, add devices, share the Obsidian vault (Send & Receive everywhere), copy syncthing/shared.stignore to ~/Documents/Obsidian/.stignore. See syncthing/README.md for write-domain rules and conflict handling.

Development

bash scripts/ceo-config.test.sh         # config loader / path helpers
bash scripts/ceo-cron.test.sh           # dispatch + tier semantics
bash scripts/ceo-notify.test.sh         # notification helper
bash scripts/ceo-discord-report.test.sh # full-report Discord webhook helper
bash scripts/ceo-schedule.test.sh       # schedule override + collision detection
bash scripts/ceo-token-intake.test.sh   # token-intake script runner
bash scripts/count-blessings.test.sh    # blessings CLI + cache

Tests are portable across BSD (macOS) and GNU (Linux/WSL): no shuf, no sort -R, no flock, no GNU-only sed -i. Each test runs in an isolated mktemp -d.

Configuration

~/.ceo/config

Persistent config file written by ceo setup. Stores resolved vault path so scripts don't need a discovery loop on every cron tick. Roll back to inline discovery (debugging only):

cd /path/to/claude-ceo
git checkout HEAD -- scripts/ceo scripts/ceo-cron.sh scripts/ceo-gather.sh scripts/ceo-report.sh

Then re-run ceo setup to regenerate the config.

CEO_VAULT

Override the configured vault path for a single invocation:

CEO_VAULT="$HOME/Documents/Obsidian" bash scripts/ceo-token-intake.sh

ceo_augment_path

Helper in scripts/ceo-config.sh that prepends ~/.bun/bin, Homebrew, ~/.local/bin, and ~/.cargo/bin (OS-aware) to PATH. Cron starts with PATH=/usr/bin:/bin; any script that needs bun/Homebrew/user-installed CLIs sources ceo-config.sh and calls ceo_augment_path at the top. Validates $HOME is non-empty — set -u doesn't catch HOME="".

ceo_resolve_plugin_cli (0.12.1)

Resolves a Claude Code plugin-provided CLI from ~/.claude/plugins/cache/<owner>/<plugin>/<version>/ rather than relying on PATH. Plugins don't install symlinks on PATH; older standalone installs of the same tool can leave stale symlinks that resolve to deleted binaries, producing silent fall-through.

if out=$(ceo_resolve_plugin_cli "nhangen-tools/token-scope" "src/cli.ts"); then
  runtime=$(printf '%s\n' "$out" | sed -n '1p')
  entry=$(printf '%s\n' "$out" | sed -n '2p')
  "$runtime" "$entry" --since 1d
fi

Picks the highest version directory via sort -V. Returns 1 if the plugin isn't installed or the entry file is missing. ceo-token-intake.sh uses this resolver and emits a WARN to stderr when falling back to token-scope on PATH (introduced after a token-intake cron silently no-op'd against a stale symlink — see nhangen/claude-ceo#37 / #38).

Per-user schedule overrides

Playbook frontmatter schedule: is the default. Per-user overrides live in $CEO_DIR/schedules.json:

{
  "morning-scan": "50 8 * * 1-5",
  "morning-brief": "57 8 * * 1-5"
}

Unknown playbook names and invalid cron syntax warn to stderr and are ignored — never silently coerced. ceo playbook scan performs collision detection before installing the crontab; a refused scan leaves the previous good state intact. Use ceo schedule <playbook> for an interactive reschedule.

Read-tier pre-gather

ceo-gather.sh exports (and ceo-cron.sh injects) these into the SINGLE_PROMPT as <external-data> blocks:

VariableSource
PR_REVIEW_REQUESTED, PR_AUTHORED, PR_REVIEW_COUNT, PR_AUTHORED_COUNTgh pr list per repo
PENDING_COUNT, APPROVED_COUNTCEO/approvals/pending.md
TODAY_LOG_SUMMARY, YESTERDAY_LOG_SUMMARYCEO/log/<date>.md
DAILY_NOTE_TOP3, DAILY_NOTE_TASKSDaily/<date>.md
BRIEFINGS_TRAININGCEO/training/briefings.md
ACTIVE_DOMAINS_CONTENTProfile.md → ## Active Domains
PENDING_ASK_QUESTIONSPending.md lines containing [ask] (top 20)
BLESSINGS_TODAYCEO/cache/blessings-today.md
VAULT_CHANGES_BY_DOMAIN, etc.ceo-scan.sh (morning-scan only)

When writing or editing a read-tier playbook, do not ask Claude to Read files. Reference pre-gathered values directly in the playbook's Steps section. New file in the prompt → add an export to ceo-gather.sh and an inject site to ceo-cron.sh.

Discord full reports

Status/failure alerts use discord_webhook. Full report delivery uses a separate webhook so it can target a different Discord channel:

{
  "discord_webhook": "https://discord.com/api/webhooks/...",
  "discord_report_webhook": "https://discord.com/api/webhooks/..."
}

Store that JSON at ~/.config/claude-ceo/secrets.json, or set CEO_DISCORD_REPORT_WEBHOOK for one-off testing. By default, the full-report poster sends morning-brief only. Override the allowlist in CEO/settings.json:

{
  "discord_report_triggers": ["morning-brief"]
}

The full report is split across multiple Discord messages when it exceeds Discord's message limit.

Architecture

Authority tiers

TierActionsExecution pathApproval
readScan vault, read PRs, generate briefingsSingle call (no Bash/Write/Edit)Auto
low-stakes-writeCreate branches, run tests, post PR commentsThree-phase PLAN/FILTER/EXECUTEAuto + report
high-stakesPush code, merge PRs, create PRsFiltered out of EXECUTE; written to approvals/pending.mdPropose + wait

Vault structure

CEO/
├── AGENTS.md          — global rules for ALL agents (tiers, constraints)
├── IDENTITY.md        — CEO-specific identity and personality
├── TRAINING.md        — rules learned from corrections
├── training/          — domain-specific training rules
├── playbooks/         — step-by-step workflows (frontmatter drives registration)
├── registry.json      — derived dispatch table
├── settings.json      — runtime config (cooldown, branch_prefix, …)
├── repos.md           — registry of cloned repos
├── inbox.md           — shared task queue for the inbox playbook
├── inbox/             — per-host task queues written by automated intakes
├── blessings.md       — gratitude list
├── approvals/         — pending high-stakes proposals
├── cache/             — derived state
├── delegations/       — task hand-offs
├── reports/           — daily report files
└── log/               — execution logs

CLIs

ceo:

ceo setup            First-time machine setup (deps, git, ssh, cron)
ceo next             Redisplay post-setup steps
ceo doctor           Check system health (deps, vault, cron, auth)
ceo test             Smoke test: trigger morning-brief, check log
ceo cron <name>      Manually run a cron trigger
ceo chat [name]      Interactive playbook (no cron); empty = triage conversation; defaults to --effort medium
ceo playbook scan|list|info     Self-registering playbook management
ceo playbook scan --dry-run     Preview what scan would install, no writes
ceo schedule [name]  List effective schedules; with name, reschedule one
ceo preflight        Preview what cron would run vs skip

Override interactive chat effort with CEO_CHAT_EFFORT=low|medium|high|xhigh|max.

count-blessings — gratitude list surfaced in the morning brief under ## Personal / ### Blessings:

count-blessings add "text"   Append a blessing
count-blessings list         Show all blessings, numbered
count-blessings show         Show today's three picks

Slash skills (Claude Code)

CommandDescription
/ceoRead vault, propose prioritized actions
/ceo:statusPending approvals, recent log, blocked items
/ceo:briefGenerate morning briefing on demand
/ceo:delegateHand off a task
/ceo:trainAdd a training rule or playbook
/ceo:logToday's execution log

Known Limitations

  • WSL2 cron does not auto-start at boot. Add [boot] command = service cron start to /etc/wsl.conf, or set up a Windows Task Scheduler job that runs wsl.exe -u <user> -- /etc/init.d/cron start at logon.
  • Portable timeout. ceo-cron.sh uses timeout (Linux) or gtimeout (macOS via brew install coreutils). If neither is installed, the wrapper degrades to no wall-clock cap (--max-turns and API timeout still apply) and a WARN is logged.
  • Schedule collisions are refused, not coerced. Two cron-trigger playbooks on the same minute would race the global /tmp/ceo-cron.lock; ceo playbook scan refuses to install the crontab until you resolve via ceo schedule <playbook> or by editing schedules.json.
  • Playbook frontmatter schema. See docs/playbooks/SCHEMA.md for the full field reference. status: is now an enum (active / draft / disabled) — drafts are runnable on-demand but never cron-installed, disabled tears down previously-installed cron lines. Unknown status values are rejected at parse time.

License

MIT.

Ver o original no GitHub

Bom para

Relacionados