# add-compact

Adopt this skill: https://proskills.md/skills/other/trsdn-nanopielot-github-skills-add-compact

Page: https://proskills.md/skills/other/trsdn-nanopielot-github-skills-add-compact
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: .github/skills/add-compact/SKILL.md
size: 6890
upstream: https://github.com/trsdn/nanopielot/blob/main/.github/skills/add-compact/SKILL.md

````text
---
name: add-compact
description: Add /compact command for manual context compaction. Solves context rot in long sessions by forwarding the SDK's built-in /compact slash command. Main-group or trusted sender only.
---

# Add /compact Command

Adds a `/compact` session command that compacts conversation history to fight context rot in long-running sessions. Uses Copilot CLI's built-in `/compact` slash command — no synthetic system prompts.

**Session contract:** `/compact` keeps the same logical session alive. The SDK returns a new session ID after compaction (via the `init` system message), which the agent-runner forwards to the orchestrator as `newSessionId`. No destructive reset occurs — the agent retains summarized context.

## Phase 1: Pre-flight

Check if `src/session-commands.ts` exists:

```bash
test -f src/session-commands.ts && echo "Already applied" || echo "Not applied"
```

If already applied, skip to Phase 3 (Verify).

## Phase 2: Apply Code Changes

Merge the skill branch:

```bash
git fetch upstream skill/compact
git merge upstream/skill/compact
```

> **Note:** `upstream` is the remote pointing to `trsdn/nanopielot`. If using a different remote name, substitute accordingly.

This adds:
- `src/session-commands.ts` (extract and authorize session commands)
- `src/session-commands.test.ts` (unit tests for command parsing and auth)
- Session command interception in `src/index.ts` (both `processGroupMessages` and `startMessageLoop`)
- Slash command handling in `container/agent-runner/src/index.ts`

### Validate

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

### Rebuild container

```bash
./container/build.sh
```

### Restart service

```bash
launchctl kickstart -k gui/$(id -u)/com.nanopielot  # macOS
# Linux: systemctl --user restart nanopielot
```

## Phase 3: Verify

### Integration Test

1. Start NanoPieLot in dev mode: `npm run dev`
2. From the **main group** (self-chat), send exactly: `/compact`
3. Verify:
   - The agent acknowledges compaction (e.g., "Conversation compacted.")
   - The session continues — send a follow-up message and verify the agent responds coherently
   - A conversation archive is written to `groups/{folder}/conversations/` (by the PreCompact hook)
   - Container logs show `Compact boundary observed` (confirms SDK actually compacted)
   - If `compact_boundary` was NOT observed, the response says "compact_boundary was not observed"
4. From a **non-main group** as a non-admin user, send: `@<assistant> /compact`
5. Verify:
   - The bot responds with "Session commands require admin access."
   - No compaction occurs, no container is spawned for the command
6. From a **non-main group** as the admin (device owner / `is_from_me`), send: `@<assistant> /compact`
7. Verify:
   - Compaction proceeds normally (same behavior as main group)
8. While an **active container** is running for the main group, send `/compact`
9. Verify:
   - The active container is signaled to close (authorized senders only — untrusted senders cannot kill in-flight work)
   - Compaction proceeds via a new container once the active one exits
   - The command is not dropped (no cursor race)
10. Send a normal message, then `/compact`, then another normal message in quick succession (same polling batch):
11. Verify:
    - Pre-compact messages are sent to the agent first (check container logs for two `runAgent` calls)
    - Compaction proceeds after pre-compact messages are processed
    - Messages **after** `/compact` in the batch are preserved (cursor advances to `/compact`'s timestamp only) and processed on the next poll cycle
12. From a **non-main group** as a non-admin user, send `@<assistant> /compact`:
13. Verify:
    - Denial message is sent ("Session commands require admin access.")
    - The `/compact` is consumed (cursor advanced) — it does NOT replay on future polls
    - Other messages in the same batch are also consumed (cursor is a high-water mark — this is an accepted tradeoff for the narrow edge case of denied `/compact` + other messages in the same polling interval)
    - No container is killed or interrupted
14. From a **non-main group** (with `requiresTrigger` enabled) as a non-admin user, send bare `/compact` (no trigger prefix):
15. Verify:
    - No denial message is sent (trigger policy prevents untrusted bot responses)
    - The `/compact` is consumed silently
    - Note: in groups where `requiresTrigger` is `false`, a denial message IS sent because the sender is considered reachable
16. After compaction, verify **no auto-compaction** behavior — only manual `/compact` triggers it

### Validation on Fresh Clone

```bash
git clone <your-fork> /tmp/nanopielot-test
cd /tmp/nanopielot-test
claude  # then run /add-compact
npm run build
npm test
./container/build.sh
# Manual: send /compact from main group, verify compaction + continuation
# Manual: send @<assistant> /compact from non-main as non-admin, verify denial
# Manual: send @<assistant> /compact from non-main as admin, verify allowed
# Manual: verify no auto-compaction behavior
```

## Security Constraints

- **Main-group or trusted/admin sender only.** The main group is the user's private self-chat and is trusted (see `docs/SECURITY.md`). Non-main groups are untrusted — a careless or malicious user could wipe the agent's short-term memory. However, the device owner (`is_from_me`) is always trusted and can compact from any group.
- **No auto-compaction.** This skill implements manual compaction only. Automatic threshold-based compaction is a separate concern and should be a separate skill.
- **No config file.** NanoPieLot's philosophy is customization through code changes, not configuration sprawl.
- **Transcript archived before compaction.** The existing `PreCompact` hook in the agent-runner archives the full transcript to `conversations/` before the SDK compacts it.
- **Session continues after compaction.** This is not a destructive reset. The conversation continues with summarized context.

## What This Does NOT Do

- No automatic compaction threshold (add separately if desired)
- No `/clear` command (separate skill, separate semantics — `/clear` is a destructive reset)
- No cross-group compaction (each group's session is isolated)
- No changes to the container image, Dockerfile, or build script

## Troubleshooting

- **"Session commands require admin access"**: Only the device owner (`is_from_me`) or main-group senders can use `/compact`. Other users are denied.
- **No compact_boundary in logs**: The SDK may not emit this event in all versions. Check the agent-runner logs for the warning message. Compaction may still have succeeded.
- **Pre-compact failure**: If messages before `/compact` fail to process, the error message says "Failed to process messages before /compact." The cursor advances past sent output to prevent duplicates; `/compact` remains pending for the next attempt.
````

## File: README.md
upstream: https://github.com/trsdn/nanopielot/blob/main/README.md

````text
<p align="center">
  <img src="assets/banner.jpeg" alt="NanoPieLot" width="600">
</p>

<h3 align="center">🥧 Easy as Pie.</h3>

<p align="center">
  <a href="https://github.com/qwibitai/nanoclaw">NanoClaw</a>, ported to the GitHub Copilot SDK — same claw, different cockpit. 🧑‍✈️
</p>

<p align="center">
  <a href="LICENSE"><img src="https://img.shields.io/github/license/trsdn/nanopielot" alt="License"></a>
  <a href="package.json"><img src="https://img.shields.io/badge/dynamic/json?url=https%3A%2F%2Fraw.githubusercontent.com%2Ftrsdn%2Fnanopielot%2Fmain%2Fpackage.json&query=%24.engines.node&label=node&color=blue&logo=nodedotjs" alt="Required Node version"></a>
  <a href="https://github.com/trsdn/nanopielot/actions/workflows/ci.yml"><img src="https://github.com/trsdn/nanopielot/actions/workflows/ci.yml/badge.svg?branch=main" alt="CI"></a>
  <a href="https://github.com/trsdn/nanopielot/releases/latest"><img src="https://img.shields.io/github/v/release/trsdn/nanopielot" alt="Latest release"></a>
  <a href="docs/conformance.md"><img src=".github/badges/conformance.svg" alt="Repository quality standard conformance"></a>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/runtime-GitHub_Copilot_SDK-blue?logo=github" alt="Copilot SDK">
</p>

---

**Status:** actively maintained, best-effort, as a personal project of
[@trsdn](https://github.com/trsdn). It is for a developer comfortable forking a
repository, running Docker or Apple Container, and authenticating the GitHub
Copilot CLI — not a packaged app a non-developer installs by name.

**Language:** this project's interface, documentation, and source are English
only; no localized builds are published.

## What Changed from NanoClaw

NanoPieLot is a full port of [NanoClaw](https://github.com/qwibitai/nanoclaw) from Anthropic/Claude to the GitHub Copilot SDK:

- **Any Copilot model.** `/model list` to see what's available, `/model <id>` to switch. GPT-4.1, Claude, Gemini — whatever your GitHub plan gives you.
- **Same architecture.** Everything else works exactly like [NanoClaw](https://github.com/qwibitai/nanoclaw): containers, channels, skills, groups, scheduling.
- Authentication via `copilot login` device flow.

## Quick Start

```bash
gh repo fork trsdn/nanopielot --clone
cd nanopielot
copilot
```

Then run `/setup`.

> Commands prefixed with `/` (like `/setup`, `/add-whatsapp`) are CLI agent skills. Type them inside the `copilot` prompt, not in your regular terminal.

## Requirements

- macOS, Linux, or Windows (via WSL2)
- Node.js 20+
- GitHub Copilot CLI
- Apple Container (macOS) or Docker (macOS/Linux)

## Migration from NanoClaw

If you are migrating an existing NanoClaw setup or maintaining a fork, read the NanoPieLot-specific migration notes in [docs/MIGRATION.md](docs/MIGRATION.md).

## Troubleshooting

For common NanoPieLot-specific deployment and runtime problems, see [docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md).

## Architecture

```
Channels → SQLite → Polling loop → Container (GitHub Copilot SDK) → Response
```

Single Node.js process. Channels self-register at startup. Agents run in isolated Linux containers. Per-group message queue with concurrency control.

## Data and privacy

NanoPieLot runs on infrastructure you provide and control; this project itself
collects nothing.

| Question | Answer |
|---|---|
| What is collected | Nothing by this project: no telemetry, no analytics, no crash reporting. |
| Where data goes | The channels you enable (WhatsApp, Telegram, Slack, Discord, Gmail) and the GitHub Copilot API, which your agent containers call to respond. No other outbound destination. |
| Who receives your content | GitHub (via the Copilot SDK/API) and whichever chat platforms you connect. Their own terms and privacy policies govern what they do with it. |
| What is stored locally | Conversation and group state in SQLite at `store/messages.db`, per-group memory under `groups/`, and the Copilot device-login session under `data/copilot-auth/`. All on the machine you run it on. |
| Retention | Kept until you delete the data directory or the group; nothing is sent anywhere for retention beyond the platforms above. |

## Accessibility

NanoPieLot has no graphical interface of its own; every surface is either a
chat platform's own client (WhatsApp, Telegram, Slack, Discord, Gmail — their
accessibility, not this project's) or plain-text console/log output during
setup and debugging, which uses no colour-only signalling.

## Security and support

Report a vulnerability privately through GitHub's [private vulnerability
reporting](https://github.com/trsdn/nanopielot/security/advisories/new). Ask
for help by opening an issue with the `/debug` skill's output; see
[docs/TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md) first.

## Contributing Workflow

For issue-driven work, create a dedicated branch and merge via pull request. Avoid developing feature or issue work directly on `main`.

## Special Thanks

NanoPieLot wouldn't exist without [NanoClaw](https://github.com/qwibitai/nanoclaw). The original project's philosophy, architecture, and skill system are the foundation of everything here. We just swapped the engine. 🥧

Forked from upstream commit [`a3fb3be`](https://github.com/qwibitai/nanoclaw/commit/a3fb3beb6ac28757e0a3dbe3b64862cd4839f8ce) (2026-03-28).

## License

MIT — see [LICENSE](LICENSE)
````
