Vine

Coding agent CLI with native Trellis workflow, powered by PI.

What is Vine?

Vine is a terminal-based coding agent that understands your project's development workflow. It reads your .trellis/ directory for task state, coding specs, and workflow configuration, then injects that context into every AI interaction — so the agent always knows what you're working on, what phase you're in, and what coding standards to follow.

Unlike wrapping an existing CLI with hooks (the old approach), Vine has Trellis built into its core. Specs are injected natively, subagents get the right guidelines automatically, and task phase tracking happens in real-time.

Install

# Run directly
npx @mindfoldhq/vine

# Or install globally
npm install -g @mindfoldhq/vine
vine

Features

• Native Trellis workflow — reads .trellis/ task state, specs, and config directly. No hooks, no Python scripts, no subprocess overhead.
• 6-phase workflow state machine — brainstorm → research → implement → check → update-spec → record-session, with artifact-based gates and auto-advancement.
• Subagent system — Agent tool dispatches specialized subagents (implement, check, research), each with phase-specific coding specs loaded from JSONL files.
• Agent definitions — loaded from .trellis/agents/*.md with YAML frontmatter (name, tools, model per-agent). Auto-scaffolded on first run.
• Event hooks — configurable event_hooks in .trellis/config.yaml for external integrations. CC-compatible stdin/stdout JSON protocol. Supports SessionStart, PreToolUse (can block), PostToolUse (can patch), SubagentStart/Stop, AgentEnd, and more.
• 15+ LLM providers — Anthropic, OpenAI, Google, DeepSeek, Mistral, xAI, OpenRouter, Bedrock, Azure, and more via PI's multi-provider support.
• MCP support — connect external tool servers via .trellis/mcp.json.
• Web search — built-in DuckDuckGo search, no API key required.
• Workflow skills — /brainstorm, /check, /update-spec, /record-session available as slash commands.
• Status line — real-time task + phase display: [P2] Task name · implement → check
• Full TUI — PI's interactive terminal UI with streaming output, markdown rendering, model switching, session management.
• OAuth login — ChatGPT Plus/Pro (Codex) subscription login. API keys for all other providers.

Quick Start

# From any project with .trellis/ initialized
vine

# With a prompt
vine "fix the bug in api.ts"

# One-shot mode
vine --print "explain this project"

# Help
vine --help

API Keys

export ANTHROPIC_API_KEY=sk-ant-...
export OPENAI_API_KEY=sk-...
export OPENROUTER_API_KEY=sk-or-...
export DEEPSEEK_API_KEY=...
# Or use OAuth: vine → /login

Architecture

packages/
├── cli/                    CLI entry point + scaffolding
│   └── main.ts             Runtime creation, system prompt, skill/agent scaffold
│   └── scaffold-skills.ts  Auto-creates .agents/skills/ on first run
│
├── trellis-core/           Trellis workflow engine (pure logic)
│   ├── schemas.ts           Zod schemas (task.json, config.yaml, event hooks)
│   ├── config.ts            Config parser (hooks + event_hooks dual-track)
│   ├── context.ts           Session context assembly
│   ├── spec-loader.ts       JSONL spec loading for agent prompt injection
│   ├── task.ts              Task lifecycle + advancePhase()
│   ├── hook-runner.ts       Event hook execution engine (spawn, stdin/stdout, timeout)
│   └── detect.ts            .trellis/ directory detection
│
├── pi-trellis-extension/   PI extension + tools
│   ├── extension.ts         PI lifecycle hooks, workflow state machine,
│   │                        event hook bridge, status line
│   ├── dispatch-tool.ts     Agent tool — subagent spawning with spec injection,
│   │                        SubagentStart/Stop hooks
│   ├── advance-phase-tool.ts  Phase advancement with pre-flight artifact gate
│   ├── agent-defs.ts        Agent definition discovery (.trellis/agents/*.md)
│   ├── web-search-tool.ts   DuckDuckGo web search
│   └── system-prompt.ts     Vine's system prompt (with workflow discipline rules)
│
├── mcp/                    MCP client
│   └── ...                  Discovery, connection, tool bridging
│
└── pi-ai/                  forked PI LLM API (Anthropic OAuth removed)

How it connects

┌──────────────────────────────────────────────────────┐
│                    vine (CLI)                         │
│  Scaffold skills/agents → Build system prompt →       │
│  Create PI runtime with Trellis extension             │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│              pi-trellis-extension                     │
│                                                       │
│  session_start → load context + MCP + run hooks       │
│  before_agent_start → inject workflow status + specs   │
│  tool_call → PreToolUse hooks (can block) + auto-phase │
│  tool_result → PostToolUse hooks (can patch) + advance │
│  Agent tool → spawn subagent with specs from JSONL     │
│  advance_phase → pre-flight artifact gate              │
└──────────────────────┬───────────────────────────────┘
                       │
┌──────────────────────▼───────────────────────────────┐
│                PI (pi-coding-agent)                    │
│  Agent loop, tools (read/bash/edit/write/grep/find),  │
│  TUI, session management, auto-compact, streaming     │
└──────────────────────────────────────────────────────┘

Workflow State Machine

Each task follows a 6-phase workflow:

brainstorm → research → implement → check → update-spec → record-session

| Phase | What happens | Advancement | |-------|-------------|-------------| | brainstorm | Clarify requirements, create PRD, fill JSONL | User confirms → advance_phase() | | research | Agent(research) analyzes codebase, writes context files | Auto-advances on agent completion | | implement | Agent(implement) writes code following specs | Auto-advances on agent completion | | check | Agent(check) reviews code, self-fixes issues | Auto-advances on agent completion | | update-spec | Update .trellis/spec/ with new patterns | User confirms → advance_phase() | | record-session | Run add_session.py to capture progress | User confirms → advance_phase() |

Artifact gates: advance_phase() refuses to advance if deliverables are missing (e.g., no prd.md for brainstorm, empty JSONL for research).

Status line shows current phase in real-time:

[P2] Hook system — configurable event hooks · implement → check

Event Hooks

Configure external hooks in .trellis/config.yaml:

event_hooks:
  PreToolUse:
    - matcher: "bash"
      command: "python3 .trellis/hooks/check-dangerous-cmd.py"
      timeout: 10
  SessionStart:
    - command: "python3 .trellis/hooks/inject-context.py"
  AgentEnd:
    - command: "curl -X POST http://localhost:3000/webhook"
      timeout: 5

Hooks use CC-compatible stdin/stdout JSON protocol:

• Input (stdin): { "event": "PreToolUse", "toolName": "bash", "toolInput": {...}, "cwd": "..." }
• Output (stdout): { "result": "continue" } or { "result": "block", "reason": "..." }

Supported events: SessionStart, BeforeAgentStart, PreToolUse, PostToolUse, SubagentStart, SubagentStop, AgentEnd, Compact, SessionEnd.

Agent Definitions

Agents are loaded from .trellis/agents/*.md (auto-scaffolded on first run):

---
name: research
description: Code and tech search expert.
tools: read, bash, edit, write, grep, find, ls, web_search
model: openrouter/anthropic/claude-sonnet-4
---

# Research Agent

[agent instructions in markdown...]

| Agent | Purpose | Tools | |-------|---------|-------| | implement | Write code following specs | Full (read, bash, edit, write, grep, find, ls) | | check | Review code, self-fix issues | Full | | research | Find patterns, write context files, populate JSONL | Full |

Configuration

~/.trellis/                    # Global config
├── auth.json                  # OAuth tokens
├── settings.json              # Model preferences (defaultProvider, defaultModel)
├── sessions/                  # Conversation history
├── skills/                    # Global skills
└── mcp.json                   # Global MCP servers

.trellis/                      # Project config
├── config.yaml                # Project config (packages, hooks, event_hooks)
├── workflow.md                # Workflow documentation
├── agents/                    # Agent definitions (implement.md, check.md, research.md)
├── tasks/{id}/                # Task directories
│   ├── task.json              # Task metadata + next_action state machine
│   ├── prd.md                 # Requirements
│   ├── implement.jsonl        # Specs for implement agent
│   ├── check.jsonl            # Specs for check agent
│   └── context/               # Research context files
├── spec/                      # Coding guidelines
└── scripts/                   # Python scripts (get_context, task management)

.agents/skills/                # Workflow skills (auto-scaffolded)
├── brainstorm/SKILL.md
├── check/SKILL.md
├── update-spec/SKILL.md
└── record-session/SKILL.md

Tools

| Tool | Description | |------|-------------| | read | Read file contents | | bash | Execute shell commands | | edit | Edit files (search & replace) | | write | Create/overwrite files | | grep | Search file contents (ripgrep) | | find | Find files by pattern | | ls | List directory contents | | Agent | Spawn a subagent (implement/check/research) | | web_search | Search the web (DuckDuckGo) | | advance_phase | Advance workflow to next phase (with artifact gate) |

Slash Commands

| Command | Description | |---------|-------------| | /brainstorm | Requirements discovery skill | | /check | Code quality review skill | | /update-spec | Update coding specs skill | | /record-session | Record session progress skill | | /trellis:status | Show current task status | | /trellis:specs | Show loaded specs for each agent type | | /trellis:phase <n> | Set task phase by number or action name | | /mcp | Show MCP server connections | | /model | Switch model | | /login | OAuth provider login |

Tech Stack

• Runtime: Node.js
• Language: TypeScript (strict)
• Schemas: Zod (all external data validated)
• Package manager: pnpm (workspace monorepo)
• Agent engine: PI (pi-coding-agent)
• MCP: @modelcontextprotocol/sdk
• Bundle: esbuild (single-file ESM, ~11 MB)
• TUI: pi-tui (differential rendering, markdown, autocomplete)

Publishing

# Publish to npm
./scripts/publish.sh          # latest tag
./scripts/publish.sh beta     # beta tag

Published as @mindfoldhq/vine on npm. Single esbuild bundle with zero npm dependencies.

License

AGPL-3.0