Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
142 lines (103 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

142 lines (103 loc) · 4.67 KB

Contributing to Myco

Myco is a plugin for collective agent intelligence, supporting Claude Code and Cursor. This guide covers development setup and project conventions. For architecture details, see Lifecycle docs.

Installing Myco (End Users)

claude plugin marketplace add goondocks-co/myco
claude plugin install myco@myco-plugins

Then in any project:

/myco-setup

This sets up the vault, configures your LLM backend, and starts capturing session knowledge.

Requirements

  • Node.js 22+
  • Claude Code or Cursor
  • An LLM backend: Ollama (recommended) or an Anthropic API key

For Ollama, pull the recommended models:

ollama pull gpt-oss
ollama pull nomic-embed-text

Development Setup

1. Clone and install

git clone https://github.com/goondocks-co/myco.git
cd myco
npm install

2. Run locally

For active development (per-session, no install needed):

claude --plugin-dir /path/to/myco

For persistent local dev (survives across sessions):

claude plugin marketplace add /path/to/myco/.claude-plugin
claude plugin install myco

3. Initialize the vault

/myco-setup

For dogfooding, the vault lives at ~/.myco/vaults/myco/ (configured via MYCO_VAULT_DIR in .claude/settings.json).

4. Verify

node dist/src/cli.js stats

Development Workflow

Build and test

make build             # lint + test + tsc + copy templates
make check             # lint + test only (pre-commit gate)
make watch             # tsc watch mode
make clean             # remove dist/

After code changes

Hooks pick up new code on the next invocation. The daemon must be restarted separately:

make build && node dist/src/cli.js restart

Project Structure

myco/
├── .claude-plugin/        # Claude Code + VS Code plugin manifest + marketplace
├── .cursor-plugin/        # Cursor plugin manifest + marketplace
├── hooks/                 # Hook registration shell scripts
├── skills/                # Agent skills
├── src/
│   ├── agents/            # Agent adapters (Claude Code, Cursor) — transcript parsing + image capture
│   ├── capture/           # Event buffering + buffer-based turn fallback
│   ├── config/            # Config schema and loader
│   ├── context/           # Context injection for UserPromptSubmit hook
│   ├── daemon/            # Long-lived HTTP daemon: session lifecycle, batch processing, plan watching
│   ├── hooks/             # Hook entry points (thin — delegate to daemon)
│   ├── index/             # SQLite FTS5 + sqlite-vec vector search
│   ├── intelligence/      # LLM backends (Ollama, LM Studio, Anthropic)
│   ├── mcp/               # MCP server + tool handlers
│   ├── prompts/           # LLM prompt templates
│   └── vault/             # Reader, writer, Zod schemas for vault notes
├── tests/                 # Mirrors src/ structure
├── docs/                  # Lifecycle, quickstart, doc site
└── Makefile               # Dev shortcuts

Architecture

See docs/lifecycle.md for the full lifecycle with diagrams. Key points:

  • Hooks are thin — they delegate to the daemon via HTTP. No business logic in hooks.
  • The daemon is the authority — all event processing, session note writing, and observation extraction happen there.
  • Transcripts are the source of truth — session conversation turns are read from the agent's native transcript file (Claude Code .jsonl, Cursor .txt/.jsonl), not from Myco's event buffer. The buffer is the fallback when no transcript is available.
  • Session notes are rebuilt — on each stop event, the full conversation is re-parsed from the transcript and the session note is regenerated. Data preservation is guaranteed by the transcript being append-only.

Distribution

Published as @goondocks/myco on npmjs.org.

  1. Push to main — CI runs lint + tests
  2. Tag a release (v0.x.y) — triggers the publish workflow
  3. npm publish builds and pushes to npmjs.org
  4. Users get the new version via claude plugin update myco

Conventions

  • TypeScript strict mode, ES modules
  • tsup for bundled builds (native deps better-sqlite3/sqlite-vec are external, installed at runtime)
  • make check must pass before committing
  • Prompt templates are markdown with {{placeholder}} syntax
  • Config is YAML (myco.yaml), vault notes are markdown with YAML frontmatter
  • No magic literals — extract named constants
  • Idempotent operations by default