markbennett.ca
WIP: A simple cli for daily tangled use cases and AI integration. This is for my personal use right now, but happy if others get mileage from it! :)
Clean up README.md
+34
-26
+34
-26
README.md
+34
-26
README.md
···
1
-
# **Tangled CLI: Architecture & Implementation Plan**
1
+
# Tangled CLI: Architecture & Implementation Plan
2
2
3
-
## **1\. Project Overview**
3
+
## 1. Project Overview
4
4
5
5
**Goal:** Create a context-aware CLI for tangled.org that bridges the gap between the AT Protocol (XRPC) and standard Git. **Philosophy:** Follow the **GitHub CLI (gh)** standard: act as a wrapper that creates a seamless experience where the API and local Git repo feel like one unified tool.
6
6
7
-
## **2\. Prior Art Analysis: GitHub CLI (gh) vs. Tangled CLI**
7
+
## 2. Prior Art Analysis: GitHub CLI (gh) vs. Tangled CLI
8
8
9
9
| Feature | GitHub CLI (gh) Approach | Tangled CLI Strategy |
10
10
| :------------- | :--------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------- |
···
14
14
| **Filtering** | \--json name,url (filters fields). | **Plan:** Support basic \--json flag first. Add field filtering (--json "cloneUrl,did") to save LLM context window tokens. |
15
15
| **Extensions** | Allows custom subcommands. | _Out of Scope for V1._ |
16
16
17
-
## **3\. High-Level Architecture (Refined)**
17
+
## 3. High-Level Architecture (Refined)
18
18
19
19
The CLI acts as a "Context Engine" before it even hits the API.
20
20
`graph TD`
···
33
33
`API --> Output`
34
34
`Shell --> Output`
35
35
36
-
## **4\. Tech Stack (TypeScript)**
36
+
## 4. Tech Stack (TypeScript)
37
37
38
38
| Component | Library | Purpose |
39
39
| :---------------- | :-------------------- | :----------------------------------------------------------- |
···
45
45
| **Interactivity** | **@inquirer/prompts** | Modern prompts for humans. |
46
46
| **Formatting** | **cli-table3** | **New:** For gh-style pretty tables in Human Mode. |
47
47
48
-
## **5\. Agent Integration (The "LLM Friendly" Layer)**
48
+
## 5. Agent Integration (The "LLM Friendly" Layer)
49
49
50
50
To make this tool accessible to Claude Code/Gemini, we adopt gh's best patterns:
51
51
52
-
### **Rule 1: Context is King**
52
+
### Rule 1: Context is King
53
53
54
54
LLMs often hallucinate repo IDs.
55
55
56
56
- **Design:** If the user/LLM runs tangled issue list inside a folder, **do not** ask for the repo DID. Infer it.
57
57
- **Fallback:** Only error if no git remote is found.
58
58
59
-
### **Rule 2: Precision JSON (--json \<fields\>)**
59
+
### Rule 2: Precision JSON (--json \<fields\>)
60
60
61
61
LLMs have token limits. Returning a 50KB repo object is wasteful.
62
62
63
63
- **Feature:** tangled repo view \--json name,cloneUrl,description
64
64
- **Implementation:** Use lodash/pick to filter the API response before printing to stdout.
65
65
66
-
### **Rule 3: The CLAUDE.md Context**
66
+
### Rule 3: Fail Fast, Fail Loud
67
67
68
-
Include this file in the repo so Claude knows how to drive the CLI.
69
-
`# Tangled CLI Cheatsheet`
70
-
71
-
`## Principles`
72
-
``1. **Context Aware:** Run commands inside the repo directory. The CLI infers the repo DID from `git remote`.``
73
-
``2. **Flags:** Always use `--json` and `--no-input`.``
74
-
75
-
`## Common Tasks`
76
-
``- **Setup:** `tangled auth login --username <handle> --password <app-password>` (One time)``
77
-
`` - **Init:** `tangled repo create <name> --json` -> `git remote add tangled <url>` ``
78
-
``- **Issues:** `tangled issue list --json title,number` (Uses current dir context)``
68
+
LLMs can't read error messages buried in HTML or long stack traces. Provide a `--no-input` flag that forces the CLI to error if it can't resolve context or if required flags are missing.
79
69
80
-
## **6\. Implementation Roadmap**
70
+
## 6. Implementation Roadmap
81
71
82
-
### **Phase 1: Context & Auth (The "Plumbing")**
72
+
### Phase 1: Context & Auth (The "Plumbing")
83
73
84
74
1. **Auth Storage:** Store the AT Proto session in conf.
85
75
2. **Context Resolver:**
···
88
78
- Regex matches the Tangled DID from the URL.
89
79
- Returns the repo param required by XRPC.
90
80
91
-
### **Phase 2: CRUD Commands (The "Porcelain")**
81
+
### Phase 2: CRUD Commands (The "Porcelain")
92
82
93
83
1. **repo create:**
94
84
- Creates record via XRPC.
···
96
86
2. **issue list/create:**
97
87
- Uses getRepoFromContext() so the user just types tangled issue create.
98
88
99
-
### **Phase 3: The "Machine" View**
89
+
### Phase 3: The "Machine" View
100
90
101
91
1. Implement a generic Formatter class.
102
92
- Formatter.render(data, { json: true, fields: \['id', 'name'\] })
103
93
- If json: pick fields, JSON.stringify.
104
94
- If human: use cli-table3.
105
95
106
-
## **7\. Example: The Context Pattern**
96
+
## 7. Example: The Context Pattern
107
97
108
98
This is how we solve the usability problem (and the LLM hallucination problem).
99
+
109
100
`// src/lib/context.ts`
110
101
`import simpleGit from 'simple-git';`
111
102
···
132
123
`throw new Error("Could not infer repository context. Please use --repo <did> or run this inside a Tangled repository.");`
133
124
`}`
134
125
135
-
### **Summary of Improvements**
126
+
### Summary of Improvements
136
127
137
128
- **Context Inference:** This is the "killer feature" of gh that we are copying. It makes the tool usable for humans and safer for LLMs (less typing \= fewer errors).
138
129
- **Filtered JSON:** Saves tokens for LLM context windows.
139
130
- **Git Config Integration:** Treats the local .git folder as a database of configuration, reducing the need for environment variables or complex flags.
131
+
132
+
### Examples Tangled CLI Usage
133
+
134
+
```bash
135
+
tangled auth login
136
+
tangled repo create my-new-repo
137
+
cd my-new-repo
138
+
tangled issue create "Bug: Something is broken"
139
+
tangled issue list --json "id,title"
140
+
```
141
+
142
+
### Outstanding Issues
143
+
144
+
1. Can we allow auth through the web browser, rather than just CLI username/password? This would be more secure and user-friendly.
145
+
2. The GitHub CLI manages the private keys allowing you to authenticate git operations. Can we do something similar, or will users have to manage SSH keys separately? Currently, I store my SSH keys in 1Password which signs requests for me. It would be great if tangled CLI could detect this and use it seamlessly, itentifying the user by the signed ssh key.
146
+
3. How should we handle storing the AT Proto session securely? The GitHub CLI uses the OS keychain. We could do something similar.
147
+
4. How are settings resolved (e.g. local config file, home folder, command-line flags)? We should define a clear precedence order.