Metadata-Version: 2.4
Name: engaku
Version: 1.1.13
Summary: AI persistent memory layer for VS Code Copilot
License: MIT
Project-URL: Homepage, https://github.com/JorgenLiu/engaku
Project-URL: Repository, https://github.com/JorgenLiu/engaku
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# engaku

AI persistent memory layer for VS Code Copilot — keeps project context, rules, and active tasks in front of the agent at every turn through VS Code Agent Hooks.

## What it does

`engaku` gives VS Code Copilot durable project memory stored in `.ai/` Markdown files. Agent Hooks automatically inject current context into every conversation, surface active-task steps on each prompt, and remind the agent when a task plan is complete and ready for review.

## Installation

```bash
pip install engaku
```

Or install directly from source:

```bash
pip install git+https://github.com/JorgenLiu/engaku.git
```

## Quick Start

```bash
# Bootstrap .ai/ and .github/ structure in your repo
engaku init
```

After running `init`, VS Code Agent Hooks are active. The `@coder`, `@planner`, `@reviewer`, and `@scanner` agents are available via `.github/agents/`. No further manual steps are needed — hooks fire automatically on SessionStart, SubagentStart, UserPromptSubmit, Stop, and PreCompact.

## What `engaku init` creates

```
.ai/
  overview.md       — project description, constraints, tech stack
  engaku.json       — model, MCP tool, and hook Python runtime config
  tasks/            — planner-managed task plans
  decisions/        — architecture decision records
.github/
  copilot-instructions.md   — global agent rules
  agents/           — coder, planner, reviewer, scanner agent definitions
  instructions/     — lessons and agent-boundaries.instructions.md stubs
  skills/           — bundled skills (systematic-debugging, verification-before-completion, etc.)
.vscode/
  settings.json     — enables VS Code custom agent hooks
  mcp.json          — MCP server configuration (chrome-devtools, context7, dbhub)
  dbhub.toml        — DBHub MCP guardrail/template config
```

`engaku init --no-mcp` skips both `.vscode/mcp.json` and `.vscode/dbhub.toml`, along with the MCP-related skills.

When MCP support is enabled, `engaku init` grants `chrome-devtools/*` to the planner agent by default (alongside `context7/*` and `dbhub/*`), so planner can run browser-backed research and verification before producing plans. `engaku update` does not modify an existing `.ai/engaku.json` — once written, your MCP tool allocations stay user-owned.

## Subcommands

| Command | Purpose |
|---------|---------|
| `init` | Bootstrap `.ai/`, `.github/` structure and install VS Code Agent Hooks |
| `inject` | Inject `.ai/overview.md` + active-task context (SessionStart / PreCompact hook) |
| `prompt-check` | Detect rule/constraint in user prompt and inject active-task steps (UserPromptSubmit hook) |
| `task-review` | Detect completed task plans and emit handoff reminder (Stop hook) |
| `apply` | Apply `.ai/engaku.json` model, MCP tool, and hook Python runtime config to `.github/agents/` frontmatter |
| `update` | Sync generated agents and skills from bundled templates, merge MCP server additions, and apply `.ai/engaku.json` config |

## How it works

After `engaku init`, five Agent Hooks fire automatically:

- **`SessionStart`** → `engaku inject`: injects `overview.md` and the active-task's remaining unchecked steps at the start of every session.
- **`PreCompact`** → `engaku inject`: injects the full task body (Background, Design, File Map, and all checkbox lines) before conversation compaction so the compact model retains full task context.
- **`SubagentStart`** → `engaku inject`: gives reviewer subagent sessions the same project and active-task context before verification begins.
- **`UserPromptSubmit`** → `engaku prompt-check`: scans each user prompt for new rules or constraints and injects all remaining unchecked task steps as a system message so the agent always knows what to do next.
- **`Stop`** → `engaku task-review`: after each agent turn, checks whether all steps in an in-progress task plan are ticked and emits a handoff reminder if so.

## Requirements

- Python 3.8 or newer (stdlib only, no third-party dependencies)
- VS Code with GitHub Copilot

> **Python 3.8 baseline:** v1.1.x continues to support Python 3.8. The future Python 3.11 migration remains deferred.

## Configuration

### Hook Python interpreter

By default, generated Agent Hooks call `engaku <subcommand>` directly, relying on `engaku` being on the system `PATH`. If `engaku` is only available inside a virtual environment, set the `python` key in `.ai/engaku.json` and run `engaku apply` (or `engaku update`) to rewrite all hook commands:

```json
{
  "python": ".venv/bin/python"
}
```

With this set, `engaku apply` rewrites every Engaku-managed hook command to `.venv/bin/python -m engaku <subcommand>`. Relative and absolute interpreter paths are both accepted. Set to `null` (the default) to restore the plain `engaku <subcommand>` form.

If the default `engaku` command is already broken, run the interpreter directly to apply the change:

```sh
.venv/bin/python -m engaku apply
```



## Global kernel and lossless compactness

Engaku policy lives in `.github/copilot-instructions.md` as an **Engaku Global Kernel**: agent ownership boundaries, Caveman-inspired lossless compactness rules, and generated artifact style in one unconditional file. `.github/instructions/` remains path-specific; hooks inject dynamic state only.

Lossless compactness: preserve complete technical substance (code, paths, commands, exact error text, decisions, verification results) while removing ceremony — no `Now let me…` filler, no repeated summaries, no arbitrary answer caps.

Teams that want Caveman's exact compression modes can install it separately: `npx skills add JuliusBrussee/caveman -a github-copilot`. Engaku uses its own Caveman-inspired rules and does not copy upstream skill text.

## MCP Servers

`engaku init` creates `.vscode/mcp.json` with three preconfigured MCP servers that give VS Code Copilot structured tool access to browser automation, live library documentation, and databases. Use `engaku init --no-mcp` to skip this entirely.

`engaku update` adds any missing server entries to an existing `.vscode/mcp.json` without overwriting your customizations.

### chrome-devtools-mcp

[github.com/ChromeDevTools/chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) — Browser automation and DevTools via Puppeteer. Provides screenshot capture, page navigation, element interaction, JavaScript evaluation, Lighthouse performance audits, and network request inspection.

**Prerequisites:** Node.js + Chrome

```json
{
  "chrome-devtools": {
    "command": "npx",
    "args": ["-y", "chrome-devtools-mcp@latest", "--headless"]
  }
}
```

### context7

[github.com/upstash/context7](https://github.com/upstash/context7) — Live, version-specific library documentation. Two tools: `resolve-library-id` (search by name) and `query-docs` (fetch current docs). HTTP remote mode — no local process needed.

**Prerequisites:** None (network access only). Set `CONTEXT7_API_KEY` env var for higher rate limits.

```json
{
  "context7": {
    "type": "http",
    "url": "https://mcp.context7.com/mcp"
  }
}
```

### dbhub

[github.com/bytebase/dbhub](https://github.com/bytebase/dbhub) — Multi-database access supporting PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite. Two tools: `search_objects` (schema exploration) and `execute_sql` (query execution).

**Prerequisites:** Node.js. Requires a DSN connection string (VS Code prompts on first use; the prompt is password-protected so the value is not stored in plain text). `engaku init` generates `.vscode/dbhub.toml` as an editable template with `readonly = true` and `max_rows = 1000` guardrails; secrets stay in the password-protected MCP input and never touch the TOML file.

```json
{
  "dbhub": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "@bytebase/dbhub@latest", "--transport", "stdio", "--config", "${workspaceFolder}/.vscode/dbhub.toml"],
    "env": {
      "DBHUB_DSN": "${input:db-dsn}"
    }
  }
}
```

The generated `.vscode/dbhub.toml`:

```toml
[[sources]]
id   = "default"
dsn  = "${DBHUB_DSN}"
lazy = true

[[tools]]
name     = "execute_sql"
source   = "default"
readonly = true
max_rows = 1000
```

Edit `.vscode/dbhub.toml` to add more sources, enable writes, or change row limits. For inline `--dsn` without a TOML file (manual override), replace `--config …` and the `env` block with `"--dsn", "${input:db-dsn}"` directly in `.vscode/mcp.json`.

## Optional MCP Servers

These servers are not generated by `engaku init`. Add them manually to `.vscode/mcp.json` when needed.

### GitHub MCP

Interact with GitHub repositories, issues, and pull requests via the official GitHub MCP server.

```json
{
  "github": {
    "type": "http",
    "url": "https://api.githubcopilot.com/mcp/"
  }
}
```

Authenticate with OAuth or a Personal Access Token. Use the `toolSets` option to restrict permissions (e.g. read-only mode). See [GitHub MCP docs](https://docs.github.com/en/copilot/customizing-copilot/using-model-context-protocol/using-the-github-mcp-server) for available toolsets and scopes.

### Firecrawl MCP

Structured web scraping and search via [Firecrawl](https://firecrawl.dev). Useful for extracting content from web pages that Context7 does not index.

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "firecrawl-key",
      "description": "Firecrawl API key",
      "password": true
    }
  ],
  "servers": {
    "firecrawl": {
      "command": "npx",
      "args": ["-y", "firecrawl-mcp"],
      "env": {
        "FIRECRAWL_API_KEY": "${input:firecrawl-key}"
      }
    }
  }
}
```

Requires a Firecrawl API key. Not a default dependency — add only when structured web research is needed.

## Bundled Skills

### skill-authoring

Helper workflow for turning a repeated multi-step method into a reusable Copilot skill. Different from VS Code's `/create-skill` command: this skill enforces an explicit primitive-selection gate (instruction file vs prompt file vs skill vs custom agent), draws a hard prompt-file-vs-skill boundary, and locks in an ownership rule — skills authored with this workflow stay user-owned and are not registered in Engaku's bundled template inventory unless an Engaku task explicitly ships them.

Use it when you notice the same phases, safeguards, and output format being re-explained across sessions and a one-shot prompt would not capture the adaptive logic between phases.

## Credits

### karpathy-guidelines skill

Adapted from [forrestchang/andrej-karpathy-skills](https://github.com/forrestchang/andrej-karpathy-skills) (MIT, Copyright © Forrest Chang), itself derived from [Andrej Karpathy's observations](https://x.com/karpathy/status/2015883857489522876).

### MCP Servers

- [chrome-devtools-mcp](https://github.com/ChromeDevTools/chrome-devtools-mcp) — browser automation and DevTools (Chrome DevTools team)
- [context7](https://github.com/upstash/context7) — live library documentation (Upstash)
- [dbhub](https://github.com/bytebase/dbhub) — multi-database access (Bytebase)
