pi-anchor 0.2.1 → 0.2.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +101 -195
- package/README_zh.md +115 -205
- package/dist/{chunk-B652T7QR.js → chunk-G72UHPBN.js} +218 -121
- package/dist/extension.cjs +286 -168
- package/dist/extension.js +73 -48
- package/dist/index.cjs +220 -121
- package/dist/index.d.cts +7 -1
- package/dist/index.d.ts +7 -1
- package/dist/index.js +5 -1
- package/package.json +1 -1
- package/src/decay.ts +54 -52
- package/src/extension.ts +74 -55
- package/src/matcher.ts +27 -6
- package/src/settlement.ts +5 -3
- package/src/store.ts +75 -18
- package/src/tui.ts +82 -59
- package/src/types.ts +1 -0
package/README.md
CHANGED
|
@@ -1,61 +1,66 @@
|
|
|
1
1
|
# ⌖ Anchor
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
<em>Stop cluttering your git history with stagnant TODOs. Maintain cross-session intent with 0 idle tokens and zero workspace pollution.</em>
|
|
6
|
-
</p>
|
|
3
|
+
> **Zero-pollution, 0-idle-token cross-session task memory for AI coding agents**
|
|
4
|
+
> Maintain cross-session intent with zero idle tokens, syntax-safe JIT touch wakeups, and zero git repository pollution.
|
|
7
5
|
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
<a href="#verification--quality-assurance">🧪 Verification</a>
|
|
16
|
-
</p>
|
|
6
|
+
[](https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml)
|
|
7
|
+
[](package.json)
|
|
8
|
+
[](tsconfig.json)
|
|
9
|
+
[](tests/store.test.ts)
|
|
10
|
+
[](package.json)
|
|
11
|
+
[](#1-zero-repository-contamination--storage-topology)
|
|
12
|
+
[](LICENSE)
|
|
17
13
|
|
|
18
|
-
|
|
19
|
-
<a href="https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml">
|
|
20
|
-
<img src="https://github.com/3ZEROS12/anchor/actions/workflows/ci.yml/badge.svg" alt="CI Status">
|
|
21
|
-
</a>
|
|
22
|
-
<img src="https://img.shields.io/badge/Node-v20+-22c55e.svg" alt="Node v20+">
|
|
23
|
-
<img src="https://img.shields.io/badge/TypeScript-Strict-3b82f6.svg" alt="TypeScript Strict">
|
|
24
|
-
<img src="https://img.shields.io/badge/Tests-26%20Passed-22c55e.svg" alt="Tests: 26 Passed">
|
|
25
|
-
<img src="https://img.shields.io/badge/Startup-%3C%2090ms-success.svg" alt="Startup: < 90ms">
|
|
26
|
-
<img src="https://img.shields.io/badge/Storage-Zero%20Repo%20Pollution-success.svg" alt="Zero Repo Pollution">
|
|
27
|
-
<img src="https://img.shields.io/badge/License-MIT-f97316.svg" alt="License: MIT">
|
|
28
|
-
</p>
|
|
14
|
+
**English** | [简体中文](./README_zh.md)
|
|
29
15
|
|
|
30
16
|
<p align="center">
|
|
31
|
-
<img src="assets/hero.svg" alt="Anchor Terminal Dashboard" width="820">
|
|
17
|
+
<img src="assets/hero-en.svg" alt="Anchor Terminal Dashboard" width="820">
|
|
32
18
|
</p>
|
|
33
19
|
|
|
20
|
+
```text
|
|
21
|
+
⌖ Anchors (4 active):
|
|
22
|
+
|
|
23
|
+
[Today · Today's Focus]
|
|
24
|
+
01 [Today] Optimize token truncation & JIT safety Desktop Today Today 10:02
|
|
25
|
+
|
|
26
|
+
[Upcoming · Scheduled]
|
|
27
|
+
02 [Upcoming] Add concurrent file lock unit tests Desktop Tomorrow Yesterday 21:34
|
|
28
|
+
03 [Upcoming] Migrate auth module to HttpOnly cookies Desktop Tomorrow Today 10:02
|
|
29
|
+
04 [Upcoming] Polish CLI interactive dashboard & TUI Desktop In 2d Today 10:02
|
|
30
|
+
|
|
31
|
+
Use `anchor done <id>` to complete.
|
|
32
|
+
```
|
|
33
|
+
|
|
34
34
|
---
|
|
35
35
|
|
|
36
36
|
## Why Anchor?
|
|
37
37
|
|
|
38
38
|
When building software with terminal-based AI coding agents (Claude Code, Pi, Aider), developers encounter three recurring points of friction:
|
|
39
39
|
|
|
40
|
-
1.
|
|
41
|
-
|
|
42
|
-
3. **Stale Task Debt**: Once code is committed, developers rarely reopen markdown files to check boxes manually. Incomplete task lists rot inside the repository indefinitely.
|
|
40
|
+
### 1. Terminal Exit = Instant Amnesia
|
|
41
|
+
Pressing `Ctrl+C` terminates the agent process, clearing working memory. Unfinished refactoring plans, temporary milestones, and cross-session agreements vanish instantly.
|
|
43
42
|
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
* `Gentleman-Programming/engram` runs a persistent background Go daemon with SQLite and continuous vector retrieval, adding daemon overhead and cross-process latency.
|
|
43
|
+
### 2. TODO.md Pollutes Git & Suffocates Token Windows
|
|
44
|
+
Writing tasks into `TODO.md` or `AGENTS.md` inside your repository creates unwanted git noise (`update todo`, `fix checklist`). Worse, **every single turn injects dozens of stagnant lines into the system prompt**, burning token budgets and diluting LLM attention on active code.
|
|
47
45
|
|
|
48
|
-
|
|
46
|
+
### 3. Checkbox Rot & Heavy Over-Engineering
|
|
47
|
+
Once code is written, developers rarely reopen markdown files to check boxes manually. Incomplete task lists rot inside the repository indefinitely. Existing alternatives introduce heavy trade-offs: `beads` forces a 200MB Dolt SQL database directly into your repository, while `engram` runs a persistent background Go daemon with SQLite and continuous vector retrieval.
|
|
48
|
+
|
|
49
|
+
**Anchor takes a lean, pragmatic approach**:
|
|
50
|
+
- **Zero Repo Contamination**: State is stored outside the workspace in `~/.anchor/state.json`, keeping your git tree 100% clean.
|
|
51
|
+
- **0 Idle Tokens**: Injects active commitments on Turn 1 cold-start; Turn 2+ working turns consume **0 tokens**. Stored tasks don't cost a dime while writing code.
|
|
52
|
+
- **Syntax-Safe JIT Wakeup**: When the agent touches relevant files, Anchor surfaces a single-line language-accurate comment (`//`, `#`, `<!-- -->`, `/* */`), while strictly skipping JSON, ENV, and lockfiles.
|
|
53
|
+
- **Auto-Settlement & Accidental Settle Guard**: Tasks automatically settle on git commits matching task descriptions or on session exit. In interactive dashboard mode, a two-stage dialog prevents accidental completion.
|
|
49
54
|
|
|
50
55
|
---
|
|
51
56
|
|
|
52
|
-
## Core Architecture
|
|
57
|
+
## Core Architecture & State Machine
|
|
53
58
|
|
|
54
59
|
```text
|
|
55
60
|
┌──────────────────────────────────────────────────────────────────────────────┐
|
|
56
61
|
│ Anchor Lifecycle State Machine │
|
|
57
62
|
└──────────────────────────────────────┬───────────────────────────────────────┘
|
|
58
|
-
│ Pin task:
|
|
63
|
+
│ Pin task: anchor "Migrate auth to HTTP-only cookies"
|
|
59
64
|
▼
|
|
60
65
|
┌───────────────────────────────────────────────┐
|
|
61
66
|
│ [ACTIVE Tier] (Turn 1 Injected) │
|
|
@@ -80,7 +85,18 @@ Existing alternatives introduce heavy trade-offs:
|
|
|
80
85
|
└──────────────────────────────┘ └────────────────────────────────┘
|
|
81
86
|
```
|
|
82
87
|
|
|
83
|
-
|
|
88
|
+
| Action / Scenario | What You Do | What Anchor Does | What the AI Gets | When to Use |
|
|
89
|
+
| :--- | :--- | :--- | :--- | :--- |
|
|
90
|
+
| **Pin Commitment** | Run `anchor "Refactor auth"` | Atomically writes to `~/.anchor/state.json` | Turn 1: Injected into prompt; Turn 2+: 0 tokens | Retaining multi-step plans across terminal restarts |
|
|
91
|
+
| **File Touch** | Edit or read code normally | Matches touched files against anchor paths | Injects syntax-safe 1-line comment (skips JSON/ENV) | Working on relevant project modules |
|
|
92
|
+
| **Git Commit** | `git commit -m "feat: ..."` | Matches commit message using `Intl.Segmenter` | Auto-settles and archives matching task | Finishing code milestones |
|
|
93
|
+
| **Session Exit** | Type `exit` / `quit` | Intersects git-modified files with active anchors | Single-keypress prompt: `[Enter Settle] / [Esc Keep]` | Wrapping up terminal session |
|
|
94
|
+
|
|
95
|
+
---
|
|
96
|
+
|
|
97
|
+
## Engineering Highlights & v0.2.1 Hardening
|
|
98
|
+
|
|
99
|
+
### 1. Zero Repository Contamination & Storage Topology
|
|
84
100
|
Anchor never creates local `.anchor` folders or touches your project git tree. All state lives safely in user-global storage:
|
|
85
101
|
```text
|
|
86
102
|
~/.anchor/
|
|
@@ -89,141 +105,78 @@ Anchor never creates local `.anchor` folders or touches your project git tree. A
|
|
|
89
105
|
├── archive.jsonl # Append-only log of settled tasks
|
|
90
106
|
└── graveyard.jsonl # Append-only log of decayed and evicted items
|
|
91
107
|
```
|
|
92
|
-
|
|
93
|
-
* **
|
|
94
|
-
* **
|
|
95
|
-
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
*
|
|
100
|
-
*
|
|
101
|
-
|
|
102
|
-
|
|
103
|
-
|
|
104
|
-
|
|
105
|
-
|
|
106
|
-
|
|
108
|
+
* **Zero-Dependency Exclusive Lock**: Uses Node's native `fs.openSync(lockPath, 'wx')` to ensure atomic serialization across concurrent tabs or agents.
|
|
109
|
+
* **Dead PID Reclamation**: Automatically reclaims stale locks if the owning process terminated (`process.kill(pid, 0)` fails) or exceeded the 5000ms timeout.
|
|
110
|
+
* **Resilient Atomic Writes**: State writes use a temporary file followed by atomic `fs.renameSync` with spin-retries for Windows NTFS locks.
|
|
111
|
+
|
|
112
|
+
### 2. Accidental Settle Guard & Details Inspector (v0.2.1)
|
|
113
|
+
Pressing Enter in `/anchor` presents a two-stage action menu:
|
|
114
|
+
* `✓ Settle`: Completes and archives the task with an undo notice (`/anchor undo to revert`).
|
|
115
|
+
* `ℹ View details & associated files`: Inspects full description, target date, files, and physical verification command without completing the task.
|
|
116
|
+
* `↩ Cancel`: Returns safely without mutating state.
|
|
117
|
+
|
|
118
|
+
### 3. Invariant 11 Token Clamping (v0.2.1)
|
|
119
|
+
Visual string truncation in dashboard headers automatically strips trailing open brackets (`(`, `[`, `{`, `（`, `【`) right before ellipsis markers (`...`), eliminating dangling punctuation artifacts.
|
|
120
|
+
|
|
121
|
+
### 4. 0-Token Idle Economy & Multi-Language Syntax-Safe JIT
|
|
122
|
+
* **Turn 1 (Cold Start)**: Injects active commitments for the current workspace alongside natural conversational guidelines.
|
|
123
|
+
* **Turn 2+ (Working Turns)**: Anchor strips task lists from subsequent turns. Stored tasks consume **0 tokens** while coding.
|
|
107
124
|
* **Syntax-Safe Guard (Strict Null)**: For **JSON, ENV, Lockfiles, and binary assets**, Anchor explicitly returns `null`, preventing corrupted parsers or invalid syntax.
|
|
108
|
-
* **Session Deduplication**: Matched tasks are injected only once per session per file to keep tool results clean.
|
|
109
|
-
|
|
110
|
-
### 3. Decoupled Universal Agent Protocol
|
|
111
|
-
Anchor separates its core state management from host environments:
|
|
112
|
-
* **`AnchorProtocol`**: Harness-agnostic engine orchestrating state transitions, decay sweeps, JIT annotations, and settlement matching.
|
|
113
|
-
* **`AgentAdapter`**: A lightweight bridge (`name`, `getCwd()`, `notify()`) enabling drop-in integration with Pi, Claude Code, Cursor, Aider, or custom MCP servers.
|
|
114
|
-
|
|
115
|
-
### 4. Dual-Timeline: Deadlines & Task Aging
|
|
116
|
-
Anchor organizes tasks along two complementary temporal axes:
|
|
117
|
-
* **Target Delivery (`targetDate`)**: Expected completion date. Natural language keywords (today, tonight, tomorrow, friday, next week) map directly to structured ISO dates. Rendered in UI as `Today`, `Tomorrow`, `In 2d`, `Daily`, `Someday`.
|
|
118
|
-
* **Creation Timestamp (`createdAt`)**: Physical creation time. Rendered in UI as `Today 10:02`, `Yesterday 21:34`, or `09-24 15:30`.
|
|
119
|
-
|
|
120
|
-
The dashboard groups active tasks into four categories:
|
|
121
|
-
* **`[Today]`**: Items due today or overdue. Priority target for the current session.
|
|
122
|
-
* **`[Upcoming]`**: Scheduled future commitments (tomorrow, upcoming weekdays, specific dates via `--due friday`).
|
|
123
|
-
* **`[Habits]`**: Recurring daily practices (such as regular backups or review habits). Completing today auto-reawakens the task tomorrow.
|
|
124
|
-
* **`[Backlog]`**: Architectural visions without explicit deadlines (`Someday`).
|
|
125
|
-
|
|
126
|
-
### 5. Zero-Friction Evidence Settlement
|
|
127
|
-
* **Git Commit Resolution**: Recognizes commit messages across Latin and CJK character sets via standard `Intl.Segmenter`. Commits matching task descriptions auto-settle the corresponding anchor.
|
|
128
|
-
* **Exit Settlement Interception**: Session exit evaluates files modified in Git. If touched files intersect with active anchors, Anchor prompts a single-keypress resolution dialog:
|
|
129
|
-
```text
|
|
130
|
-
⌖ Settle Anchor Task
|
|
131
|
-
Task #anc-1 [Migrate auth to HTTP-only cookies] touched files (src/auth/jwt.ts).
|
|
132
|
-
Mark as completed and archive? [Enter Confirm] / [Esc Keep]
|
|
133
|
-
```
|
|
134
|
-
* **Instant Reversion**: Run `anchor undo` to restore the last settled task back into `state.json`.
|
|
135
125
|
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
## Interface Design
|
|
139
|
-
|
|
140
|
-
### Status Bar Indicator
|
|
141
|
-
* When active tasks exist: Displays task count `⌖ 4` in the terminal status row.
|
|
142
|
-
* Zero tasks: 100% invisible (0 characters rendered).
|
|
143
|
-
|
|
144
|
-
### Global CLI (`anchor`) & Interactive TUI (`/anchor`)
|
|
145
|
-
```text
|
|
146
|
-
⌖ Anchors (4 active):
|
|
126
|
+
### 5. Pre-Flight Physical Verification
|
|
127
|
+
When an anchor declares a `verifyCommand`, the runner executes it on session start. Tasks that pass auto-settle immediately, freeing cognitive space.
|
|
147
128
|
|
|
148
|
-
|
|
149
|
-
01 [Today] Optimize token truncation & JIT safety Desktop Today Today 10:02
|
|
129
|
+
---
|
|
150
130
|
|
|
151
|
-
|
|
152
|
-
02 [Upcoming] Add concurrent file lock unit tests Desktop Tomorrow Yesterday 21:34
|
|
153
|
-
03 [Upcoming] Polish CLI interactive dashboard Desktop Tomorrow Today 10:02
|
|
154
|
-
04 [Upcoming] Publish npm package v0.2.0 Desktop In 2d Today 10:02
|
|
131
|
+
## Commands & Usage
|
|
155
132
|
|
|
156
|
-
|
|
133
|
+
### Standalone CLI
|
|
134
|
+
```bash
|
|
135
|
+
anchor # List active tasks (Neovim-style dashboard)
|
|
136
|
+
anchor "Migrate auth to cookies" # Pin new commitment
|
|
137
|
+
anchor "Submit report" --due friday # Pin with explicit deadline
|
|
138
|
+
anchor done 1 # Complete row 1 (ordered index support)
|
|
139
|
+
anchor done anc-5 # Complete by explicit ID
|
|
140
|
+
anchor undo # Restore last archived task
|
|
157
141
|
```
|
|
158
|
-
|
|
159
|
-
|
|
160
|
-
|
|
142
|
+
|
|
143
|
+
### Pi Coding Agent Commands
|
|
144
|
+
| Command | Description |
|
|
145
|
+
| :--- | :--- |
|
|
146
|
+
| `/pin "task description"` | Pin an anchor task for the current workspace |
|
|
147
|
+
| `/anchor` | Open interactive terminal task dashboard |
|
|
148
|
+
| Status bar `⌖ N` | Displays active task count in status row; 100% hidden when 0 tasks exist |
|
|
161
149
|
|
|
162
150
|
---
|
|
163
151
|
|
|
164
|
-
## Comparison
|
|
152
|
+
## Technical Comparison
|
|
165
153
|
|
|
166
154
|
| Feature | `gastownhall/beads` | `Gentleman-Programming/engram` | `AGENTS.md` / `TODO.md` | **Anchor ⚓** |
|
|
167
155
|
| :--- | :--- | :--- | :--- | :--- |
|
|
168
|
-
| **
|
|
169
|
-
| **Concurrency Safety** | SQL Transaction locks | Daemon single-point | Git merge conflicts | **Zero-dep cross-process atomic file lock** |
|
|
156
|
+
| **Architecture** | Distributed SQL Graph | Vector/SQLite Memory | Static Markdown | **Decoupled Universal Protocol + Atomic State** |
|
|
170
157
|
| **Workspace Hygiene** | Pollutes repo with 200MB Dolt | System daemon | **Pollutes git commit history** | **100% Zero repo pollution (`~/.anchor/`)** |
|
|
171
158
|
| **Token Cost** | Medium/High per turn | High (full prompt injection) | Severe (stale text accumulates) | **0 Tokens idle (JIT file touch only)** |
|
|
172
|
-
| **
|
|
173
|
-
| **Task Timeline** | Flat list | Flat list | Static checklist | **Dual-timeline (Due Date + Task Age)** |
|
|
159
|
+
| **Syntax Safety** | N/A | Raw text injection | Static unformatted | **Language-aware comments, strictly skips JSON** |
|
|
174
160
|
| **Closure Mechanism** | Manual CLI close | Passive storage | Manual file edit | **Git Commit auto-match + One-tap exit settlement** |
|
|
175
|
-
| **
|
|
161
|
+
| **Concurrency Safety** | SQL Transaction locks | Daemon single-point | Git merge conflicts | **Zero-dep cross-process atomic file lock** |
|
|
176
162
|
| **Startup Overhead** | Heavy CLI init | Go daemon | None | **< 90ms pre-bundled production artifact** |
|
|
177
163
|
| **Dependencies** | External Dolt binary | External Go binary | None | **Zero native binary dependencies (Pure TS)** |
|
|
178
164
|
|
|
179
165
|
---
|
|
180
166
|
|
|
181
|
-
##
|
|
182
|
-
|
|
183
|
-
### 1. Global CLI
|
|
184
|
-
```bash
|
|
185
|
-
# Global installation
|
|
186
|
-
npm install -g pi-anchor
|
|
187
|
-
|
|
188
|
-
# Or instant invocation via npx
|
|
189
|
-
npx pi-anchor
|
|
190
|
-
```
|
|
191
|
-
|
|
192
|
-
Command summary:
|
|
193
|
-
```bash
|
|
194
|
-
anchor # List active tasks
|
|
195
|
-
anchor "Refactor auth cookies" # Pin new commitment
|
|
196
|
-
anchor "Submit report" --due friday # Pin with explicit deadline
|
|
197
|
-
anchor done 1 # Complete row 1
|
|
198
|
-
anchor undo # Restore last archived task
|
|
199
|
-
```
|
|
167
|
+
## Author's Note
|
|
200
168
|
|
|
201
|
-
|
|
202
|
-
```typescript
|
|
203
|
-
import { AnchorStore, AnchorProtocol } from 'pi-anchor';
|
|
169
|
+
The motivation behind Anchor came from a recurring headache during pair-programming with AI coding agents: watching `TODO.md` and `AGENTS.md` rot inside my git trees.
|
|
204
170
|
|
|
205
|
-
|
|
206
|
-
|
|
171
|
+
Every time a task remained unfinished across sessions, writing it to a project markdown file felt harmless at first. Over weeks of work, two frictions became unbearable:
|
|
172
|
+
1. In multi-turn sessions, the AI dragged dozens of stagnant task lines into the prompt on every single turn, burning hundreds of tokens while diluting the model's focus on the actual code being edited.
|
|
173
|
+
2. Merge conflicts on task checklists in Git commits polluted the repository's history with irrelevant bookkeeping noise.
|
|
207
174
|
|
|
208
|
-
|
|
209
|
-
protocol.handleSessionStart();
|
|
175
|
+
When I looked at existing solutions, the trade-offs felt disproportionate. Stuffing a 200MB Dolt SQL relational database into the repository root (`beads`), or running a background Go daemon with SQLite and continuous vector retrieval (`engram`), inverted the relationship between tool and developer. A task tracker should not demand more system resources than the application being built.
|
|
210
176
|
|
|
211
|
-
|
|
212
|
-
const turn1Prompt = protocol.handleBeforeTurn(1, process.cwd());
|
|
177
|
+
Anchor takes the opposite approach: store state outside the project tree in a lean global ledger (`~/.anchor/state.json`), inject tasks only on Turn 1 of a cold start, keep Turn 2+ at exactly 0 tokens, and auto-settle upon git commits or session exit.
|
|
213
178
|
|
|
214
|
-
|
|
215
|
-
const { annotation } = protocol.handleToolResult({
|
|
216
|
-
toolName: 'read',
|
|
217
|
-
filePath: 'src/auth.ts',
|
|
218
|
-
cwd: process.cwd()
|
|
219
|
-
});
|
|
220
|
-
```
|
|
221
|
-
|
|
222
|
-
### 3. Pi Coding Agent Extension
|
|
223
|
-
Install into user extensions:
|
|
224
|
-
```bash
|
|
225
|
-
pi install npm:pi-anchor
|
|
226
|
-
```
|
|
179
|
+
In v0.2.1, we added the two-stage settle menu to eliminate accidental completions and enhanced visual truncation to prevent dangling punctuation. I hope Anchor keeps your project trees clean and your focus where it belongs: on the code.
|
|
227
180
|
|
|
228
181
|
---
|
|
229
182
|
|
|
@@ -232,60 +185,13 @@ pi install npm:pi-anchor
|
|
|
232
185
|
Engineered with strict TypeScript and 100% standard library test coverage using Node's native test runner:
|
|
233
186
|
|
|
234
187
|
```bash
|
|
235
|
-
npm run build # Dual ESM/CJS compilation via tsup + declaration emit
|
|
236
188
|
npm run typecheck # Strict tsc --noEmit check (0 errors)
|
|
237
|
-
npm test # Native Node test runner (
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
```text
|
|
241
|
-
✔ ContextInjector - renders only active anchors, sleeping consume 0 tokens
|
|
242
|
-
✔ ContextInjector - renders targetDate and task aging in prompt
|
|
243
|
-
✔ ContextInjector - renders preflight failure hints into cold-start context
|
|
244
|
-
✔ AnchorDecay - status evaluation transitions
|
|
245
|
-
✔ AnchorDecay - sweepStore transitions and graveyard eviction
|
|
246
|
-
✔ AnchorMatcher - exact, prefix, and tag matching
|
|
247
|
-
✔ AnchorMatcher - glob pattern matching (*.ts, src/**/*.ts)
|
|
248
|
-
✔ AnchorMatcher - findMatchedAnchors prioritizes high-confidence & high-priority
|
|
249
|
-
✔ SessionTouchObserver - records read, edit, write and commits
|
|
250
|
-
✔ SessionTouchObserver - matches CJK commit messages with segmentation
|
|
251
|
-
✔ SessionTouchObserver - separates read inspection from edit mutation
|
|
252
|
-
✔ Lock - acquireSyncLock acquires, holds, and releases exclusive lockfile
|
|
253
|
-
✔ Lock - acquireSyncLock safely reclaims stale lock from dead PID
|
|
254
|
-
✔ Context - makeSafeTaskAnnotation produces language-accurate comments and skips JSON
|
|
255
|
-
✔ Protocol - AnchorProtocol lifecycle handles cold-start and safe JIT
|
|
256
|
-
✔ AnchorStore - basic CRUD & atomic writes
|
|
257
|
-
✔ AnchorStore - corrupt state recovery
|
|
258
|
-
✔ AnchorStore - daily recurring task completes for today and wakes tomorrow
|
|
259
|
-
✔ AnchorStore - temporal durability keywords and project detection
|
|
260
|
-
✔ AnchorStore - atomicRenameWithRetry successfully replaces files atomically
|
|
261
|
-
✔ AnchorTUI - status bar reflects active state cleanly with ⌖ N
|
|
262
|
-
✔ AnchorTUI - formatTargetDate and formatCreationTime render clear dual-timeline
|
|
263
|
-
✔ AnchorTUI - openAnchorDashboard renders Plan 2 Neovim/Geek layout with folder metadata
|
|
264
|
-
✔ AnchorTUI - getDisplayWidth and padToWidth properly align CJK full-width columns
|
|
265
|
-
✔ AnchorTUI - updateStartupBanner renders clean widget above editor
|
|
266
|
-
✔ AnchorTUI - truncateToWidth properly handles ANSI escape sequences and bounds width
|
|
267
|
-
|
|
268
|
-
ℹ pass 26, fail 0
|
|
189
|
+
npm test # Native Node test runner (29/29 passing)
|
|
190
|
+
npm run build # Dual ESM/CJS compilation via tsup + declaration emit
|
|
269
191
|
```
|
|
270
192
|
|
|
271
193
|
---
|
|
272
194
|
|
|
273
|
-
## Author's Note
|
|
274
|
-
|
|
275
|
-
The motivation behind Anchor came from a recurring headache during pair-programming with AI coding agents: watching `TODO.md` and `AGENTS.md` rot inside my git trees.
|
|
276
|
-
|
|
277
|
-
Every time a task remained unfinished across sessions, writing it to a project markdown file felt harmless at first. But over weeks of work, two frictions became unbearable:
|
|
278
|
-
1. In multi-turn sessions, the AI dragged dozens of stagnant task lines into the prompt on every single turn, burning hundreds of tokens while diluting the model's focus on the actual code being edited.
|
|
279
|
-
2. Merge conflicts on task checklists in Git commits polluted the repository's history with irrelevant bookkeeping noise.
|
|
280
|
-
|
|
281
|
-
When I looked at existing solutions, the trade-offs felt disproportionate. Stuffing a 200MB Dolt SQL relational database into the repository root (`beads`), or running a background Go daemon with SQLite and continuous vector retrieval (`engram`), inverted the relationship between tool and developer. A developer task tracker should not demand more system resources than the application being built.
|
|
282
|
-
|
|
283
|
-
Anchor takes the opposite approach: store state outside the project tree in a lean global ledger (`~/.anchor/state.json`), inject tasks only on Turn 1 of a cold start, keep Turn 2+ at exactly 0 tokens, and auto-settle upon git commits or session exit.
|
|
284
|
-
|
|
285
|
-
I hope Anchor helps keep your project trees clean and your focus where it belongs: on the code.
|
|
286
|
-
|
|
287
|
-
---
|
|
288
|
-
|
|
289
195
|
## License
|
|
290
196
|
|
|
291
|
-
MIT
|
|
197
|
+
MIT © [Jason Song](https://github.com/3ZEROS12)
|