Metadata-Version: 2.4
Name: engaku
Version: 1.1.4
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, UserPromptSubmit, Stop, and PreCompact.

## What `engaku init` creates

```
.ai/
  overview.md       — project description, constraints, tech stack
  tasks/            — planner-managed task plans
  decisions/        — architecture decision records
.github/
  copilot-instructions.md   — global agent rules
  agents/           — coder, planner, reviewer, scanner agent definitions
  instructions/     — .instructions.md stubs for hooks, templates, tests
  skills/           — bundled skills (systematic-debugging, verification-before-completion, etc.)
.vscode/
  mcp.json          — MCP server configuration (chrome-devtools, context7, dbhub)
```

## 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 config to `.github/agents/` frontmatter |

## How it works

After `engaku init`, four 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.
- **`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 (stdlib only, no third-party dependencies)
- VS Code with GitHub Copilot

> **Python 3.8 baseline:** v1.0.x is the final release supporting Python 3.8. Users on constrained environments can pin with `pip install "engaku<1.1"`. Later releases require Python 3.11+.

## 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
```



## 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.

## 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)
