Kundun Agent

https://github.com/wgm-dev/kundun-agent
Admin
Kundun-Agent is a local-first MCP memory and codebase intelligence agent built for fast project...
Tokens:31,698
Snippets:439
Trust Score:2.8
License:Apache-2.0
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install Dependencies

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Installs project dependencies. For better-sqlite3, this step fetches a prebuilt binary.

```bash
npm install
```

--------------------------------

### Start Desktop App Command

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Command to start the visual desktop application.

```bash
kundun desktop
```

--------------------------------

### Install and Build Kundun-Agent

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/mcp-integration.md

Install project dependencies and build the CLI. This is a prerequisite for running the MCP server.

```bash
npm install
npm run build
```

--------------------------------

### One-off Kundun-Agent Initialization

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Initialize Kundun-Agent without a global installation using npx. This is useful for quick, one-off setups.

```bash
npx kundun-agent init
```

--------------------------------

### Install Dependencies and Run Tests

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CONTRIBUTING.md

Install project dependencies, build the project, and run tests. These commands are essential for setting up the development environment and verifying changes.

```bash
npm install
npm run build
npm test
```

--------------------------------

### Start Kundun Daemon

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/dashboard.md

Start the Kundun daemon from your project root. The daemon will print the API URL and the dashboard URL, along with the token location.

```bash
kundun daemon
```

--------------------------------

### Start MCP Server

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Start the MCP server, which allows integration with AI coding assistants like Claude Code or Cursor.

```bash
kundun mcp
```

--------------------------------

### Install Kundun-Agent CLI

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Install the Kundun-Agent CLI globally using npm. This allows you to use the `kundun` command directly from your terminal.

```bash
npm install -g kundun-agent
kundun --help
```

--------------------------------

### Local Usage Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Example commands for local usage of the kundun-agent.

```bash
npx kundun-agent init
npx kundun-agent scan
npx kundun-agent mcp
```

--------------------------------

### Full Kundun Configuration Example

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/configuration.md

This JSON object shows all available configuration keys with their default values. You can use a partial file, as missing keys will adopt these defaults.

```json
{
  "projectName": "my-project",
  "databasePath": ".kundun/kundun.sqlite",
  "include": ["src", "app", "database", "routes", "config", "docs"],
  "exclude": [
    "node_modules",
    "vendor",
    ".git",
    ".next",
    "dist",
    "build",
    "coverage",
    "storage",
    "logs",
    "tmp",
    ".kundun"
  ],
  "maxFileSizeKb": 512,
  "scanBinaryFiles": false,
  "enableDiagnostics": true,
  "enableAutoCleanup": true,
  "allowRestartFromMcp": false,
  "autoScan": {
    "enabled": false,
    "intervalMinutes": 10
  },
  "cleanup": {
    "deleteDeletedFilesAfterDays": 7,
    "deleteUnusedChunksAfterDays": 30,
    "deleteLowImportanceMemoriesAfterDays": 60,
    "archiveCompletedTasksAfterDays": 30,
    "deleteLogsAfterDays": 14,
    "vacuumAfterCleanup": true
  },
  "desktop": {
    "enabled": true,
    "minimizeToTray": true,
    "startWithWindows": false,
    "localApiHost": "127.0.0.1",
    "localApiPort": 37373
  },
  "languages": {
    "php": true,
    "go": true,
    "typescript": true,
    "javascript": true,
    "csharp": true,
    "cpp": true,
    "sql": true
  }
}
```

--------------------------------

### MCP Integration Configuration

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Example configuration for integrating with MCP servers, specifying the command, arguments, and environment variables.

```json
{
  "mcpServers": {
    "kundun-agent": {
      "command": "npx",
      "args": ["-y", "kundun-agent", "mcp"],
      "env": {
        "KUNDUN_PROJECT_ROOT": "/path/to/project"
      }
    }
  }
}
```

--------------------------------

### Go Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of code patterns that Go diagnostics should detect. Focuses on error handling, concurrency, and state management.

```text
ignored errors
goroutines without visible context/cancellation
context not propagated
possible race-prone shared state
```

--------------------------------

### Search Everything

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/search.md

A basic example of searching for a specific term across the entire indexed codebase.

```bash
kundun search "createUser"
```

--------------------------------

### SQL Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of SQL code patterns that diagnostics should detect, focusing on potentially dangerous queries.

```text
SELECT *
UPDATE without WHERE
DELETE without WHERE
dynamic SQL concatenation
missing transaction around critical updates
```

--------------------------------

### PHP Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of code patterns that PHP diagnostics should detect. These are heuristic and do not execute project code.

```text
SQL queries concatenated with variables
raw input usage
echo/render without escaping in suspicious contexts
missing authorization checks in mutation-like controllers
dangerous file operations
```

--------------------------------

### GET /projects

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves a list of projects managed by the Kundun Agent.

```APIDOC
## GET /projects

### Description
Retrieves a list of projects managed by the Kundun Agent.

### Method
GET

### Endpoint
/projects

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **projects** (array) - A list of project objects.
  - **name** (string) - The name of the project.
  - **root** (string) - The root directory of the project.

#### Response Example
{
  "projects": [
    {
      "name": "kundun-agent",
      "root": "/wgm-dev/kundun-agent"
    }
  ]
}
```

--------------------------------

### Get Project Summary

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cli-reference.md

Displays a read-only overview of the project, including languages, important files, memories, tasks, scan/cleanup history, counts, search mode, and suggested commands. This command takes no flags beyond global options.

```sh
kundun summary
```

--------------------------------

### GET /logs

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves logs from the Kundun Agent in real time.

```APIDOC
## GET /logs

### Description
Retrieves logs from the Kundun Agent in real time. This endpoint may also be used as a WebSocket stream for real-time log updates.

### Method
GET

### Endpoint
/logs

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **logEntries** (array) - A list of log entries.
  - **level** (string) - The log level (e.g., info, warning, error, critical).
  - **message** (string) - The log message.
  - **timestamp** (string) - The timestamp of the log entry.

#### Response Example
{
  "logEntries": [
    {
      "level": "info",
      "message": "Agent started successfully.",
      "timestamp": "2023-10-27T10:00:00Z"
    }
  ]
}
```

--------------------------------

### C# Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of C# code patterns that diagnostics should detect, particularly concerning asynchronous operations and task management.

```text
async void
Task.Result
Task.Wait
missing CancellationToken
possible incorrect DI lifetime
```

--------------------------------

### TypeScript/Next.js Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of code patterns that TypeScript and Next.js diagnostics should detect, focusing on type safety, data fetching, and API handlers.

```text
excessive any usage
fetch without error handling
server/client boundary mistakes
missing input validation
unsafe API handlers
```

--------------------------------

### Run Daemon Without Dashboard

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/dashboard.md

If you only need the API and not the static UI, start the daemon with the --no-dashboard flag. This disables static serving while keeping the API routes functional.

```bash
kundun daemon --no-dashboard
```

--------------------------------

### GET /metrics

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves recent metrics snapshots for the Kundun Agent.

```APIDOC
## GET /metrics

### Description
Retrieves recent metrics snapshots for the Kundun Agent.

### Method
GET

### Endpoint
/metrics

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **metrics** (array) - A list of recent metrics snapshots.

#### Response Example
{
  "metrics": [
    {
      "timestamp": "2023-10-27T10:05:00Z",
      "cpuUsage": 0.5,
      "memoryUsage": 0.3
    }
  ]
}
```

--------------------------------

### Skipped File Reason Schema

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Example JSON object illustrating the structure for reporting a skipped file, including its path and the reason for skipping.

```json
{
  "path": ".env",
  "reason": "sensitive_file"
}
```

--------------------------------

### Search Result Format

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/search.md

An example of a single search result, showing the file path, line number, and a snippet of the matching code.

```text
src/services/payment-service.ts:118
  async function refund(orderId: string, amount: Money) {
```

--------------------------------

### Record an Architectural Decision

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/memory-engine.md

Example of adding a memory to record an architectural decision, specifying type, title, content, tags, importance, and source.

```text
kundun memory add \
  --type decision \
  --title "Search uses SQLite FTS5, LIKE fallback" \
  --content "Primary search is FTS5 with bm25 ranking; falls back to LIKE when FTS5 is unavailable. No external embeddings in MVP1." \
  --tags search,sqlite \
  --importance 80 \
  --source architecture-review
```

--------------------------------

### GitHub Actions CI Workflow

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

This YAML defines a Continuous Integration workflow for the project, triggered on pushes to the main branch and pull requests. It sets up Node.js, installs dependencies, runs type checking, linting, testing, and builds the project.

```yaml
name: CI

on:
  push:
    branches: ['main']
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: 20

      - run: npm ci
      - run: npm run typecheck
      - run: npm run lint
      - run: npm run test
      - run: npm run build

```

--------------------------------

### Typical Kundun First Run Workflow

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/scanner-indexing.md

Initialize the project, scan and index all files, and then view a summary of the indexed content.

```bash
# 1. Initialize the project (creates kundun.config.json and .kundun/)
kundun init

# 2. Scan and index everything
kundun scan

# 3. Confirm what was indexed
kundun summary
```

--------------------------------

### Initialize and scan project

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/security.md

Initialize and scan the project. The .env file should be skipped and counted under 'skipped'.

```bash
kundun init
kundun scan
```

--------------------------------

### Initialize Kundun-Agent Project

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Creates the .kundun/ directory and configuration file. This command sets up the project for indexing and memory storage.

```bash
kundun init
```

--------------------------------

### Initialize a new kundun project

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cli-reference.md

Initializes a project, creating necessary configuration files and directories. Use --name to specify a project name, which defaults to the directory name.

```sh
kundun init --name my-service
```

--------------------------------

### Initialize and Scan Project

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/mcp-integration.md

Initialize the project for the MCP server and scan its contents. This creates necessary configuration files and databases.

```bash
node /abs/path/to/kundun-agent/dist/cli/index.js --project-root . init
node /abs/path/to/kundun-agent/dist/cli/index.js --project-root . scan
```

--------------------------------

### C++ Diagnostics Detection Examples

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Examples of C++ code patterns that diagnostics should detect, focusing on unsafe string manipulation and memory management.

```text
strcpy
sprintf
gets
manual new/delete patterns
raw buffer manipulation
unchecked pointer arithmetic
```

--------------------------------

### Create a new task

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cli-reference.md

Create a new task with a title, description, priority, and associated files.

```sh
kundun task create --title "Fix scan on symlinked dirs" \
  --priority high --files src/scanner/walk.ts
```

--------------------------------

### Explore Codebase with Search and Symbol Lookup

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Demonstrates exploring the codebase using 'search' for keywords and 'symbol' to find specific code entities like classes.

```bash
kundun search "authentication"
```

```bash
kundun symbol UserController --kind class
```

--------------------------------

### Create a Task

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/task-engine.md

Use this command to create a new task. Specify a title, and optionally add a description, priority, and related file paths. New tasks are initially set to 'pending' status.

```bash
kundun task create --title <title> [--description <d>] [--priority <p>] [--files <a,b>]
```

```bash
kundun task create \
  --title "Fix payment webhook retry loop" \
  --description "Webhook handler retries indefinitely on 5xx" \
  --priority critical \
  --files "src/payments/webhook.ts,src/payments/retry.ts"
```

--------------------------------

### Create a secret file

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/security.md

Create a sample .env file with a unique marker to test the secret-leak guarantee.

```bash
echo "API_TOKEN=SUPER_SECRET_MARKER_12345" > .env
```

--------------------------------

### GET /health

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves the current health status of the Kundun Agent.

```APIDOC
## GET /health

### Description
Retrieves the current health status of the Kundun Agent.

### Method
GET

### Endpoint
/health

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **status** (string) - The health status of the agent.

#### Response Example
{
  "status": "ok"
}
```

--------------------------------

### Recommended Desktop App Stack

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Details the recommended technology stack for building the Kundun-Agent desktop application.

```text
Go
Wails
React
TypeScript
Local HTTP API
WebSocket events
Windows tray
```

--------------------------------

### GET /sessions

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves a list of active and recent sessions managed by the Kundun Agent.

```APIDOC
## GET /sessions

### Description
Retrieves a list of active and recent sessions managed by the Kundun Agent.

### Method
GET

### Endpoint
/sessions

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **sessions** (array) - A list of session objects.
  - **client** (string) - The client associated with the session.
  - **sessionId** (string) - The unique identifier for the session.
  - **transport** (string) - The transport protocol used for the session.
  - **project** (string) - The project associated with the session.
  - **status** (string) - The current status of the session.
  - **startedAt** (string) - The timestamp when the session started.
  - **lastActivity** (string) - The timestamp of the last activity in the session.
  - **toolsCalled** (array) - A list of tools called within the session.
  - **errors** (array) - A list of errors encountered during the session.
  - **currentOperation** (string) - The current operation being performed in the session.

#### Response Example
{
  "sessions": [
    {
      "client": "desktop-app",
      "sessionId": "abc123xyz",
      "transport": "websocket",
      "project": "/path/to/project",
      "status": "active",
      "startedAt": "2023-10-27T10:00:00Z",
      "lastActivity": "2023-10-27T10:05:00Z",
      "toolsCalled": ["scan", "index"],
      "errors": [],
      "currentOperation": "indexing"
    }
  ]
}
```

--------------------------------

### Build Project

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Builds the project using tsup, outputting to dist/ in ESM format with .d.ts files. better-sqlite3 remains external.

```bash
npm run build
```

--------------------------------

### Run the Kundun-Agent Scanner

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/scanner-indexing.md

Initiates the scanning and indexing process for your project. This command is incremental by default, processing only new or modified files.

```bash
kundun scan
```

--------------------------------

### Local API Required Endpoints

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

List of required endpoints for the local API, including GET and POST requests.

```http
GET  /health
GET  /sessions
GET  /metrics
GET  /projects
GET  /logs
GET  /events

POST /scan
POST /cleanup
POST /diagnostics
POST /mcp/restart
```

--------------------------------

### Find Memories Tagged 'auth' and of Type 'bug'

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/memory-engine.md

Example of searching for memories that are specifically tagged with 'auth' and are of the 'bug' type.

```text
kundun memory search --type bug --tags auth
```

--------------------------------

### Capture Knowledge and Work Items

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Shows how to add decisions to memory and create tasks. Decisions capture learned information, while tasks define actionable work items.

```bash
kundun memory add --type decision \
  --title "Use SQLite for local storage" \
  --content "All state is local; no external services in MVP1." \
  --importance 80
```

```bash
kundun task create --title "Add retry to payment client" --priority high
```

```bash
kundun task next
```

--------------------------------

### GET /events

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Retrieves system events from the Kundun Agent. This endpoint also serves as a WebSocket stream for real-time event updates.

```APIDOC
## GET /events

### Description
Retrieves system events from the Kundun Agent. This endpoint also serves as a WebSocket stream for real-time event updates.

### Method
GET

### Endpoint
/events

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **events** (array) - A list of system events.
  - **type** (string) - The type of event (e.g., session.started, scan.completed).
  - **payload** (object) - The data associated with the event.
  - **timestamp** (string) - The timestamp of the event.

#### Response Example
{
  "events": [
    {
      "type": "scan.completed",
      "payload": {
        "filesScanned": 100,
        "filesIndexed": 95
      },
      "timestamp": "2023-10-27T10:05:00Z"
    }
  ]
}
```

--------------------------------

### Go Diagnostics Suggestion Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Commands suggested for running Go testing and static analysis tools.

```bash
go test ./...
go test -race ./...
go vet ./...
golangci-lint run
```

--------------------------------

### List Project Memory Entries

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Display all stored entries in the project's memory.

```bash
kundun memory list
```

--------------------------------

### List All Tasks

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Display all tasks currently tracked by Kundun-Agent.

```bash
kundun task list
```

--------------------------------

### JSON Output for Search

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/search.md

Use the `--json` flag to get machine-readable search results on stdout, with the search mode included in the payload.

```bash
kundun search "rate limit" --json
```

--------------------------------

### Example Scan Run Tally

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/scanner-indexing.md

A typical output after a scan run, showing the number of files scanned, added, changed, removed, skipped, and indexed.

```text
scanned=842 new=12 changed=4 removed=1 skipped=37 indexed=16
```

--------------------------------

### Get the Next Task

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/task-engine.md

Retrieves the single most important task to work on based on a predefined ordering of priority and status. Returns nothing if no task qualifies.

```bash
kundun task next
```

--------------------------------

### Run Tests

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Executes unit and integration tests using Vitest.

```bash
npm test
```

--------------------------------

### Search Provider Abstraction

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Illustrates the file structure for different search provider implementations, including SQLite FTS5, a fallback provider, and a future embedding provider.

```text
core/search-provider.ts
  sqlite-fts-provider.ts
  fallback-search-provider.ts
  future-embedding-provider.ts
```

--------------------------------

### POST /diagnostics

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Initiates a diagnostics run for the project.

```APIDOC
## POST /diagnostics

### Description
Initiates a diagnostics run for the project.

### Method
POST

### Endpoint
/diagnostics

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the diagnostics run has started.

#### Response Example
{
  "message": "Diagnostics initiated successfully."
}
```

--------------------------------

### Composition Root: AppContext Creation

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Demonstrates how the `createAppContext` function in `src/core/container.ts` initializes the application context by loading configuration, setting up the database, and building all necessary repositories and engines.

```typescript
ctx.close() in a `finally`.
```

--------------------------------

### Preview Cleanup with Dry Run

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cleanup.md

Use the `--dry-run` flag to preview cleanup actions without making any changes to the database or files. This is useful for reviewing counts before a real run.

```bash
kundun cleanup --dry-run
```

--------------------------------

### SQLite Configuration Pragmas

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

These SQL pragmas are recommended for configuring SQLite for optimal performance and reliability in the Kundun-Agent. They enable WAL journaling, enforce foreign keys, and set a busy timeout.

```sql
PRAGMA journal_mode = WAL;
PRAGMA foreign_keys = ON;
PRAGMA busy_timeout = 5000;

```

--------------------------------

### npm Commands for Testing and Building

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

These bash commands are used for building the project, running tests, linting, and type checking. They are essential for maintaining code quality and ensuring the project is ready for deployment.

```bash
npm run build

```

```bash
npm run test

```

```bash
npm run lint

```

```bash
npm run typecheck

```

--------------------------------

### Build Kundun CLI

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Builds the Kundun CLI tool. This command should be run once from the kundun-agent repository.

```bash
npm install && npm run build
```

--------------------------------

### Kundun Agent Repository Structure

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

This snippet displays the recommended directory and file structure for the Kundun Agent project. It includes configuration files, source code directories, desktop application components, documentation, and tests.

```text
kundun-agent/
  LICENSE
  NOTICE
  README.md
  CONTRIBUTING.md
  SECURITY.md
  CODE_OF_CONDUCT.md
  package.json
  tsconfig.json
  eslint.config.js
  prettier.config.js
  vitest.config.ts
  tsup.config.ts

  src/
    main.ts

    mcp/
      server.ts
      tools.ts
      resources.ts
      session-middleware.ts

    core/
      project-scanner.ts
      indexer.ts
      chunker.ts
      memory-engine.ts
      task-engine.ts
      cleanup-engine.ts
      language-detector.ts
      diagnostics-engine.ts
      health-monitor.ts
      metrics-engine.ts
      session-registry.ts
      event-bus.ts
      search-provider.ts

    storage/
      sqlite.ts
      migrations.ts
      repositories/
        file.repository.ts
        chunk.repository.ts
        symbol.repository.ts
        memory.repository.ts
        task.repository.ts
        diagnostic.repository.ts
        session.repository.ts
        health.repository.ts
        metrics.repository.ts

    languages/
      php.ts
      go.ts
      typescript.ts
      javascript.ts
      csharp.ts
      cpp.ts
      sql.ts

    config/
      config-loader.ts
      default-config.ts
      config-schema.ts

    cli/
      index.ts
      commands/
        init.ts
        scan.ts
        search.ts
        memory.ts
        task.ts
        diagnostics.ts
        cleanup.ts
        summary.ts
        mcp.ts
        daemon.ts
        desktop.ts
        status.ts
        sessions.ts
        health.ts
        logs.ts
        restart.ts

    api/
      local-server.ts
      auth.ts
      routes/
        health.routes.ts
        sessions.routes.ts
        metrics.routes.ts
        logs.routes.ts
        scan.routes.ts
        cleanup.routes.ts
        diagnostics.routes.ts

    utils/
      hashing.ts
      path-safety.ts
      ignore-rules.ts
      binary-detection.ts
      logger.ts
      time.ts
      json.ts

  desktop/
    wails.json
    main.go
    app.go
    internal/
      api-client/
      tray/
      startup/
      config/
    frontend/
      package.json
      src/
        main.tsx
        App.tsx
        pages/
          Dashboard.tsx
          Sessions.tsx
          Indexing.tsx
          Memory.tsx
          Tasks.tsx
          Diagnostics.tsx
          Health.tsx
          Logs.tsx
          Settings.tsx
        components/
        hooks/
        lib/
        styles/

  docs/
    architecture.md
    memory-engine.md
    indexing-strategy.md
    mcp-protocol.md
    desktop-app.md
    security.md
    configuration.md
    troubleshooting.md

  tests/
    fixtures/
    unit/
    integration/

```

--------------------------------

### Create a New Task

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Create a new task with a title and priority. Tasks can be used to track development work.

```bash
kundun task create --title "Add auth" --priority high
```

--------------------------------

### POST /scan

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Initiates a project scan operation.

```APIDOC
## POST /scan

### Description
Initiates a project scan operation.

### Method
POST

### Endpoint
/scan

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the scan has started.

#### Response Example
{
  "message": "Scan initiated successfully."
}
```

--------------------------------

### C# Diagnostics Suggestion Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Commands suggested for building, testing, and formatting C# projects.

```bash
dotnet build
dotnet test
dotnet format --verify-no-changes
```

--------------------------------

### Basic Search and Mode Footer

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/search.md

Perform a keyword search and observe the footer indicating the active search mode (fts5 or like).

```bash
kundun search "rate limit"
```

--------------------------------

### Run Full Check Suite

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CONTRIBUTING.md

Execute the complete suite of checks, including type checking, linting, testing, and building. This ensures code quality and correctness before submitting changes.

```bash
npm run typecheck
npm run lint
npm test
npm run build
```

--------------------------------

### Format Code

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Formats the entire codebase using Prettier, writing changes to files.

```bash
npm run format
```

--------------------------------

### Create Task with File Relations

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/task-engine.md

Use this command to create a new task and associate it with specific files in the codebase. This helps in tracking which parts of the code a task affects.

```bash
kundun task create \
  --title "Tighten session expiry" \
  --priority high \
  --files "src/auth/session.ts,src/auth/middleware.ts"
```

--------------------------------

### TypeScript/Next.js Diagnostics Suggestion Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Commands suggested for running linting, type checking, testing, and building TypeScript/Next.js projects.

```bash
npm run lint
npm run typecheck
npm run test
npm run build
```

--------------------------------

### POST /cleanup

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Initiates a cleanup operation for the project.

```APIDOC
## POST /cleanup

### Description
Initiates a cleanup operation for the project.

### Method
POST

### Endpoint
/cleanup

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **message** (string) - Confirmation message that the cleanup has started.

#### Response Example
{
  "message": "Cleanup initiated successfully."
}
```

--------------------------------

### Creating a New Core Engine/Feature Factory

Source: https://github.com/wgm-dev/kundun-agent/blob/main/CLAUDE.md

Illustrates how to create a new core engine or feature using a factory pattern. Dependencies are injected via a 'deps' object, allowing for testability by controlling time-dependent aspects.

```typescript
export function create<Feature>(deps: { now?: () => string }) {
  // ... implementation ...
}
```

--------------------------------

### Kundun CLI Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

List of essential commands for interacting with the Kundun agent via the command-line interface.

```bash
kundun init
kundun scan
kundun search "query"
kundun symbol "name"
kundun memory add
kundun memory search
kundun memory list
kundun task create
kundun task next
kundun task update
kundun task list
kundun diagnostics
kundun cleanup
kundun summary
kundun mcp
kundun daemon
kundun desktop
kundun status
kundun sessions
kundun health
kundun logs
kundun restart
```

--------------------------------

### Run Kundun Agent Cleanup

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cleanup.md

Execute the cleanup command. Use `--dry-run` to preview changes without modifying the database.

```bash
kundun cleanup [--dry-run]
```

--------------------------------

### Run kundun with a specific project root

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cli-reference.md

Use the --project-root option to operate on a project located in a directory other than the current working directory.

```sh
kundun --project-root /path/to/repo scan
```

--------------------------------

### Record Decision and Task with Details

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Persists a decision about using integer cents for money values and creates a task for adding an idempotency key to the payment endpoint.

```bash
kundun memory add --type decision \
    --title "Money values use integer cents" \
    --content "Avoid floating-point rounding; all amounts are integer cents." \
    --tags payments,money --importance 85
```

```bash
kundun task create \
    --title "Add idempotency key to payment endpoint" \
    --priority high --files src/controllers/payment.controller.ts
```

--------------------------------

### Default Desktop App and Local API Settings

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/configuration.md

Reserved settings for the desktop application and local API. These features are not part of MVP1.

```json
{
  "enabled": true,
  "minimizeToTray": true,
  "startWithWindows": false,
  "localApiHost": "127.0.0.1",
  "localApiPort": 37373
}
```

--------------------------------

### Agent Loop: Orient, Gather, Recall, Work, Record

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/getting-started.md

Outlines a typical agent loop using Kundun commands with JSON output for structured data processing. Includes orienting, gathering code, recalling memories, selecting tasks, and recording changes.

```bash
kundun summary --json
```

```bash
kundun search <query> --json
```

```bash
kundun symbol <name> --json
```

```bash
kundun memory search <query> --json
```

```bash
kundun task next --json
```

```bash
kundun scan
```

```bash
kundun memory add
```

```bash
kundun task update
```

--------------------------------

### Restart Daemon Configuration

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Configuration object required to restart the local daemon. 'allowRestartFromMcp' must be true.

```json
{
  "allowRestartFromMcp": true
}
```

--------------------------------

### Default Include Directories

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/configuration.md

Specifies the default directories that the Kundun-Agent scanner will index. These are typically source and application-related folders.

```json
[
  "src",
  "app",
  "database",
  "routes",
  "config",
  "docs"
]
```

--------------------------------

### Kundun Agent Local Project Data Structure

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

This snippet shows the expected directory structure for local project data managed by Kundun-Agent. It includes the main SQLite database, cache, logs, snapshots, and runtime configuration.

```text
.kundun/
  kundun.sqlite
  cache/
  logs/
  snapshots/
  runtime/
    token
  config.json

```

--------------------------------

### List Tasks with Filters

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/task-engine.md

Display a list of tasks, with options to filter by status and limit the number of results. Useful for reviewing pending or in-progress work.

```bash
kundun task list [--status <s>] [--limit <n>]
```

```bash
kundun task list --status in_progress
kundun task list --limit 20
```

--------------------------------

### Default Auto-Scan Daemon Settings

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/configuration.md

Reserved settings for the auto-scan daemon. These are not implemented in MVP1, and running scans must be done manually.

```json
{
  "enabled": false,
  "intervalMinutes": 10
}
```

--------------------------------

### Execute Real Cleanup

Source: https://github.com/wgm-dev/kundun-agent/blob/main/docs/en/cleanup.md

Run the `kundun cleanup` command without any flags to apply the retention policy, delete files, archive tasks, and potentially run VACUUM. This action modifies the database and file system.

```bash
kundun cleanup
```

--------------------------------

### Required License Files

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Lists the essential files that must be included in the project repository related to licensing and contribution.

```text
LICENSE
NOTICE
README.md
CONTRIBUTING.md
SECURITY.md
CODE_OF_CONDUCT.md
```

--------------------------------

### kundun.create_task Input

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Input parameters for the kundun.create_task MCP tool, used to create new tasks.

```json
{
  "title": "string",
  "description": "string optional",
  "priority": "low | medium | high | critical",
  "relatedFiles": ["string"]
}
```

--------------------------------

### Recommended Tagline for README.md

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

A concise tagline to be included in the README.md file, summarizing the project's core function.

```markdown
Kundun-Agent is a local-first MCP memory and codebase intelligence agent built for fast project scanning, persistent memory, task recovery, diagnostics, and agent-friendly context retrieval.
```

--------------------------------

### PHP Diagnostics Suggestion Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Commands suggested for running PHP static analysis and code fixing tools.

```bash
vendor/bin/phpstan analyse
vendor/bin/psalm
vendor/bin/php-cs-fixer fix --dry-run
composer test
```

--------------------------------

### C++ Diagnostics Suggestion Commands

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Commands suggested for running C++ static analysis and sanitization tools.

```bash
clang-tidy
cppcheck
asan/ubsan build when possible
```

--------------------------------

### Default SQLite Database Path

Source: https://github.com/wgm-dev/kundun-agent/blob/main/README.md

Specifies the default location for the Kundun-Agent's SQLite database file within the local project data directory.

```text
.kundun/kundun.sqlite

```
Tokens:
Raw