huytieu/COG-second-brain

What it is

COG is a skill and agent framework that turns a folder of Markdown notes into an AI-maintained personal knowledge system, intended for use with Obsidian and a coding agent such as Claude Code, Cursor, Kiro, Gemini CLI, or Codex. There is no database and no hosted service: skills read and write .md files in a vault with fixed directories for inbox, daily notes, personal and professional braindumps, projects, and consolidated knowledge.

The repository ships 43 skills and 10 agents. Skills cover capture and review (braindump, daily brief, weekly check-in, knowledge consolidation), product-management workflows, research, content production, writing and design critique, and a people CRM that promotes profiles from stubs to full profiles as mentions accumulate. Worker agents handle data-heavy steps while lead sessions do synthesis, and a separate set of read-only verifiers checks artifacts against acceptance criteria without grading the worker's own summary.

Quick start

Requirements: Git, Node.js for the optional npx install path, and one supported agent. Clone the repository and open it as the working folder:

git clone https://github.com/huytieu/COG-second-brain.git
cd COG-second-brain

Then start your agent in that folder and ask it to run onboarding: code . followed by "Run onboarding" in Claude Code, "Run onboarding" after opening the folder in Cursor or Antigravity, gemini then /onboarding in Gemini CLI, or codex then "Run onboarding" in Codex. Agents without a dedicated surface can be pointed at AGENTS.md. Alternatively, install through skills.sh:

npx skills add huytieu/COG-second-brain

Onboarding personalizes the vault and selects a role pack; it normally takes a couple of minutes. Optional configuration for Git sync, iCloud, and Obsidian Tasks is described in SETUP.md. After setup, daily use starts with a braindump or a brief request, and the results land in the corresponding vault directories.

Verification harness

The opt-in closed loop is the project's distinguishing feature. When requested, work runs a V-model: criteria are decomposed on the left, the build sits at the apex, and verification runs on the right with evidence traced back to each criterion. The four verifier agents are read-only and receive artifact paths rather than worker output. Related skills include closed-loop, ultragoal for multi-session goals, harvest for proposing skill patches, retro for auditing evidence quality, and review-cockpit for multi-item sessions. If you never ask for it, none of the checkpoints or evidence ledger run. The full lifecycle is documented in WORKFLOW.md.

Constraints

• Everything is local Markdown; the README states that no data is stored on external servers and that your agent's API is called only when you invoke a skill. Privacy therefore depends on the agent and any integrations you enable.
• Team and PM skills are strongest with GitHub CLI (gh) and Linear, Slack, and PostHog MCP integrations. They are described as degrading gracefully, so GitHub alone is a valid starting point.
• Agent coverage differs by surface: Claude Code and Antigravity get the full surface, while Kiro and Gemini CLI currently expose 7 native powers or commands, and AGENTS.md is the universal fallback.
• The closed-loop harness adds checkpoints and evidence work; it is opt-in per request or can be enabled by default for build tasks in the profile file.
• Updates separate framework files from personal content and prompt per file when customizations are detected. Git is recommended but optional.
• Licensed MIT; you pay only for your AI agent's API usage.

HotRepo's take

On 2026-11-15 the project ranked 7th on the Python daily list with 37 stars gained, which shows a burst of attention around a repository that is essentially a skill and agent configuration set rather than a conventional library. That fits the project's design: the interesting engineering is in the workflow contracts — read-only verifiers, artifact-path handoff, evidence ledgers, and anti-slop gates — which are easy to inspect and adapt without installing a runtime. The caveats are the uneven agent surfaces and the dependency on external integrations for the team features, both of which the documentation states openly.