Initial commit

Author: DonPrus

.cursor/rules/nllclw.mdc

@@ -0,0 +1,6 @@
+---
+description: nllclw project instructions
+alwaysApply: true
+---
+
+Use `AGENTS.md` as the canonical project instructions for this repository.

.github/copilot-instructions.md

@@ -0,0 +1,3 @@
+# Copilot Instructions
+
+Use `AGENTS.md` as the canonical project instructions for this repository.

.github/workflows/ci.yml

@@ -0,0 +1,36 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  zig:
+    uses: nullclaw/nullbuilder/.github/workflows/zig-ci.yml@v1
+    permissions:
+      contents: read
+    with:
+      binary_name: nllclw
+      artifact_prefix: nllclw
+      zig_version: "0.16.0"
+      test_command: |
+        zig fmt --check build.zig build.zig.zon $(find src -name '*.zig' -type f | sort)
+        zig build test --summary all
+        zig build test --summary all -Dshell-tool=true
+        zig build --release=small
+        ./zig-out/bin/nllclw --help >/dev/null
+        if strings ./zig-out/bin/nllclw | grep -E 'shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS|cmd\.exe|sh -c'; then
+          echo "default binary contains shell-only strings"
+          exit 1
+        fi
+        zig build --release=small -Dshell-tool=true
+        zig build -Dtarget=x86_64-windows --release=small
+        zig build -Dtarget=x86_64-linux --release=small
+        zig build -Dtarget=aarch64-linux --release=small
+        zig build -Dtarget=aarch64-macos --release=small
+        zig build -Dtarget=wasm32-wasi --release=small

.github/workflows/release.yml

@@ -0,0 +1,19 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write
+
+jobs:
+  release:
+    uses: nullclaw/nullbuilder/.github/workflows/zig-release.yml@v1
+    permissions:
+      contents: write
+    with:
+      binary_name: nllclw
+      artifact_prefix: nllclw
+      zig_version: "0.16.0"
+      source_archive: true

.gitignore

@@ -0,0 +1,21 @@
+.zig-cache/
+zig-out/
+.env
+config.json
+USER.md
+BOOTSTRAP.md
+.nllclw-memory.jsonl
+.nllclw-memory.jsonl.lock
+.nllclw-memory.jsonl.tmp.*
+.nllclw-facts.jsonl
+.nllclw-facts.jsonl.lock
+.nllclw-facts.jsonl.tmp.*
+.nllclw-schedule.jsonl
+.nllclw-schedule.jsonl.lock
+.nllclw-schedule.jsonl.tmp.*
+.nllclw-user-tools.jsonl
+.nllclw-user-tools.jsonl.lock
+.nllclw-user-tools.jsonl.tmp.*
+.nllclw-telegram-offset
+.nllclw-telegram-offset.lock
+.nllclw-telegram-offset.tmp.*

AGENTS.md

@@ -0,0 +1,64 @@
+# AGENTS.md
+
+This is the canonical workspace instruction file for nllclw and for coding
+agents working on this repository. nllclw loads this file into runtime context
+when it is present in the current directory. Tool-specific files in this repo
+point here.
+
+## Project
+
+nllclw is a tiny Zig 0.16 AI assistant. It is intentionally stdlib-only by
+default: no package dependencies, no `curl`, no external runtime process, and no
+shell tool unless the binary is built with `-Dshell-tool=true`.
+
+## Architecture
+
+- `src/main.zig`: process entrypoint only.
+- `src/root.zig`: small public Zig package API.
+- `src/runtime.zig`: composition root for channels, config, adapters, memory, and tools.
+- `src/agent.zig`: channel-neutral Chat Completions engine.
+- `src/chat.zig`: OpenAI-compatible Chat Completions JSON/SSE codec.
+- `src/providers.zig`: OpenAI/OpenRouter/compatible endpoint and header presets.
+- `src/config/`: runtime config types, source mapping, and validation.
+- `src/channels/`: CLI, terminal REPL, local commands, Telegram, and WebSocket orchestration.
+- `src/tools/`: product tools: time, diagnostics, filesystem, memory, web search, scheduler, macro tools, and optional shell.
+- `src/ports/`: dependency ports.
+- `src/adapters/`: stdlib implementations of ports.
+
+Keep product capabilities in `src/tools/`, technical implementations in
+`src/adapters/`, and channel loops in `src/channels/`.
+
+## Build And Test
+
+Run these before handing work back:
+
+```sh
+zig fmt build.zig build.zig.zon $(find src -name '*.zig' -type f | sort)
+zig build test --summary all
+zig build test --summary all -Dshell-tool=true
+zig build --release=small
+./zig-out/bin/nllclw --help >/dev/null
+strings ./zig-out/bin/nllclw | rg 'shell_exec|NLLCLW_SHELL|NLLCLW_TOOL_TIMEOUT_MS|cmd\.exe|sh -c' || true
+git diff --check
+```
+
+For portability-sensitive changes, also run:
+
+```sh
+zig build -Dtarget=x86_64-windows --release=small
+zig build -Dtarget=x86_64-linux --release=small
+zig build -Dtarget=aarch64-linux --release=small
+zig build -Dtarget=aarch64-macos --release=small
+zig build -Dtarget=wasm32-wasi --release=small
+```
+
+## Rules
+
+- Use Zig stdlib APIs first.
+- Preserve zero external runtime dependencies in the default binary.
+- Keep shell execution behind `-Dshell-tool=true`.
+- Do not expose channel/runtime internals from `src/root.zig`.
+- Add tests near the code for new behavior.
+- Update README metrics when release binary size, test counts, source file
+  counts, or LOC change.
+- Do not commit `.env`, `config.json`, `USER.md`, `BOOTSTRAP.md`, or generated memory files.

HEARTBEAT.md

@@ -0,0 +1,20 @@
+# HEARTBEAT.md
+
+nllclw can run one heartbeat pass with `nllclw heartbeat`, or keep a local
+polling loop alive with `nllclw daemon`.
+
+Heartbeat input is explicit: only unchecked markdown task lines and lines that
+start with `TODO:` are converted into a local prompt. Checked tasks, prose, and
+policy notes are ignored by the heartbeat runner.
+
+When a heartbeat pass runs:
+
+- State the check that was performed.
+- Report only material changes or failures.
+- Do not claim that nllclw is watching something continuously unless
+  `nllclw daemon` or an external supervisor is actually running.
+- Keep recurring task state in explicit local files, not hidden process memory.
+
+Scheduled tasks live in the app state directory (`schedule.jsonl`) by default.
+The assistant can create, list, and delete them with the `cron_set`,
+`cron_list`, and `cron_delete` tools when tools are enabled.

IDENTITY.md

@@ -0,0 +1,10 @@
+# IDENTITY.md
+
+Name: nllclw
+
+nllclw is a tiny local AI assistant for people who want one portable binary,
+OpenAI-compatible providers, local memory, optional local tools, and plain files
+they can inspect.
+
+It should feel like a compact working assistant, not a hosted platform or a
+framework with hidden services.

MEMORY.md

@@ -0,0 +1,25 @@
+# MEMORY.md
+
+nllclw has two memory layers:
+
+- Conversation transcript memory in the app state directory (`memory.jsonl`).
+- Durable fact memory in the app state directory (`facts.jsonl`).
+
+## What To Remember
+
+- User preferences that are likely to matter later.
+- Stable project facts the user asks the assistant to retain.
+- Decisions made during a conversation when they affect future behavior.
+
+## What Not To Remember
+
+- Secrets, API keys, tokens, or private credentials.
+- Temporary debugging output.
+- Guesses, uncertain claims, or facts the user did not endorse.
+
+## Memory Behavior
+
+Memory is local, plain text, and inspectable. By default it lives under the
+platform user state directory, not beside the downloaded binary or repository. A
+provider response should still be returned even if a best-effort memory write
+fails.