jacob-mathison/llm-tools
1
1
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: add claude-cli, codex-cli, cursor-cli, local-llm tool guides; sync README, llm.txt, manifest

Browse Source
This commit is contained in:
Jacob Mathison
2026-05-31 00:05:58 -05:00
parent fab3bbaf08
commit 2a8c00f80b
7 changed files with 672 additions and 2 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+9 -1
View File
@@ -34,7 +34,11 @@ llm-tools/
│ ├── aws-cli.llm.md AWS — profiles, S3, Amplify, CloudFront, Lambda
│ ├── tailscale.llm.md Tailscale network — machines, IPs, kittens
│ ├── vault.llm.md Vault secrets — paths, read patterns
│ └── k8s.llm.md k8s stack — services, ports, kubectl
│ ├── k8s.llm.md k8s stack — services, ports, kubectl
│ ├── local-llm.llm.md Local LLMs — Gemma-4-E4B (8080) + Gemma-4-26B (8081)
│ ├── claude-cli.md Claude Code CLI reference
│ ├── codex-cli.md OpenAI Codex CLI reference
│ └── cursor-cli.md Cursor IDE/CLI reference
│
├── agents/ Per-agent configuration and notes
│ ├── README.md
@@ -91,6 +95,10 @@ git clone http://100.79.253.19:3000/jacob-mathison/<repo>.git
| Network / machines | [`tools/tailscale.llm.md`](./tools/tailscale.llm.md) |
| Secrets | [`tools/vault.llm.md`](./tools/vault.llm.md) |
| k8s services | [`tools/k8s.llm.md`](./tools/k8s.llm.md) |
| Local LLMs | [`tools/local-llm.llm.md`](./tools/local-llm.llm.md) |
| Claude Code CLI | [`tools/claude-cli.md`](./tools/claude-cli.md) |
| Codex CLI | [`tools/codex-cli.md`](./tools/codex-cli.md) |
| Cursor | [`tools/cursor-cli.md`](./tools/cursor-cli.md) |
| Start here (new agent) | [`documents/onboarding.md`](./documents/onboarding.md) |
| Machine details | [`documents/machines.md`](./documents/machines.md) |
| Agent-specific config | [`agents/`](./agents/) |
llm.txt
+11
View File
@@ -31,6 +31,10 @@ New agent? Read documents/onboarding.md first — it sequences the full orientat
tailscale.llm.md Tailscale network — machine IPs, kittens bridge, connectivity
vault.llm.md Vault secrets — all credential paths, read patterns
k8s.llm.md k8s silma-ai stack — services, ports, kubectl patterns
local-llm.llm.md Local LLMs — Gemma-4-E4B (localhost:8080) + Gemma-4-26B (localhost:8081)
claude-cli.md Claude Code CLI — commands, flags, MCP, local LLM usage
codex-cli.md OpenAI Codex CLI — install, approval modes, AGENTS.md
cursor-cli.md Cursor IDE/CLI — agent mode, rules, MCP, Gitea integration
agents/ Per-agent configuration, context, and notes
README.md
@@ -109,6 +113,13 @@ Active Gitea repos:
api-keys/gemini, api-keys/nvidia, api-keys/banner-pyre, openclaw
spotify, twitter/silma, twitter/blb, reddit/silma-paws, reddit/silma-claws
## Local LLMs (Tabitha — Metal accelerated)
Gemma-4-E4B: http://localhost:8080 (fast, OpenAI-compatible)
Gemma-4-26B: http://localhost:8081 (capable, OpenAI-compatible)
Start: cd /Users/Tabitha/.openclaw && npm run api:llm
Storage: ~/.cache/huggingface -> /Volumes/Theodora/models/huggingface
## Conventions
Default branch: main
manifest.json
+5 -1
View File
@@ -188,7 +188,11 @@
"aws-cli.llm.md": "AWS account \u2014 profiles, S3 buckets, Amplify apps, CloudFront, Lambda",
"tailscale.llm.md": "Tailscale network \u2014 machine inventory, IPs, kittens bridge patterns",
"vault.llm.md": "Vault secrets \u2014 all credential paths, curl read patterns",
"k8s.llm.md": "k8s silma-ai stack \u2014 service map, ports, kubectl patterns, storage notes"
"k8s.llm.md": "k8s silma-ai stack \u2014 service map, ports, kubectl patterns, storage notes",
"claude-cli.md": "Claude Code CLI \u2014 install, commands, flags, MCP config, local LLM usage",
"codex-cli.md": "OpenAI Codex CLI \u2014 install, approval modes, AGENTS.md, local LLM usage",
"cursor-cli.md": "Cursor IDE/CLI \u2014 agent mode, rules, MCP, local LLM, Gitea integration",
"local-llm.llm.md": "Local LLMs \u2014 Gemma-4-E4B (8080) + Gemma-4-26B (8081), OpenAI-compatible API"
}
},
"agents": {
tools/claude-cli.md
+159
View File
@@ -0,0 +1,159 @@
# Claude Code CLI Guide
Claude Code is Anthropic's agentic coding tool. It reads your codebase, edits files, runs commands, and integrates with dev tools. Available as a terminal CLI, VS Code/Cursor extension, desktop app, and in-browser.
**Official docs:** https://code.claude.com/docs/en/overview
**CLI reference:** https://code.claude.com/docs/en/cli-reference
---
## Installation
```bash
# macOS / Linux / WSL (recommended — auto-updates)
curl -fsSL https://claude.ai/install.sh | bash
# Homebrew (does NOT auto-update)
brew install --cask claude-code
# npm (global)
npm install -g @anthropic-ai/claude-code
```
**Installed on:** Tabitha, Hunter's machine, Ozymandias
---
## Authentication
```bash
claude auth login # Sign in with Claude subscription (claude.ai)
claude auth login --console # Sign in with Anthropic Console (API billing)
claude auth status # Check current auth state (JSON)
claude auth status --text # Human-readable
claude auth logout
```
---
## Core CLI Commands
```bash
claude # Start interactive session
claude "query" # Start session with initial prompt
claude -p "query" # One-shot query, then exit (SDK mode)
cat file.ts | claude -p "explain" # Pipe content in
claude -c # Continue most recent conversation
claude -c -p "query" # Continue + one-shot
claude -r "session-name" "query" # Resume session by ID or name
claude update # Update to latest version
```
---
## Key Flags
| Flag | Description |
|------|-------------|
| `--model <model>` | Specify model (e.g. `claude-opus-4-5`, `claude-sonnet-4-6`) |
| `--add-dir <path>` | Add directory to allowed paths |
| `--permission-mode` | Set permission mode (`auto`, `default`, `manual`) |
| `--output-format` | `text` (default), `json`, `stream-json` |
| `--max-turns <n>` | Limit agentic loop turns |
| `--no-update-notifier` | Suppress update messages |
| `--mcp-config <file>` | Load MCP config from file |
| `--settings <file>` | Load settings from JSON file |
---
## In-Session Slash Commands
```
/help Show available commands
/status Show auth, model, context info
/model Switch model mid-session
/clear Clear conversation history
/compact Summarize conversation to save context
/memory Show loaded memory files (CLAUDE.md etc.)
/tools List available tools
/reasoning Toggle extended thinking on/off
/cost Show token usage for session
/quit Exit
```
---
## MCP Servers (Tabitha — User Scope)
Configured in `~/.claude.json`. All available in every Claude Code session on Tabitha:
```bash
claude mcp list # Show all MCPs
claude mcp add --scope user -e KEY=val -- name npx -y pkg # Add one
claude mcp remove --scope user name # Remove one
```
| MCP | What it gives Claude |
|-----|---------------------|
| `github` | GitHub API (silmaai PAT) |
| `postgres` | SQL → silma DB |
| `memory` | Knowledge graph (`memory/knowledge-graph.json`) |
| `redis` | Redis client |
| `qdrant` | Vector search on `silma` collection |
| `elasticsearch` | Full-text search |
| `minio` | S3-compatible object storage |
| `playwright` | Headless browser automation |
| `kubernetes` | `kubectl` via MCP |
| `google-workspace` | Gmail, Drive, Docs, Sheets, Calendar |
> ⚠️ postgres, redis, qdrant, elasticsearch, minio require k8s port-forward active.
---
## CLAUDE.md (Project Memory)
Claude Code automatically loads `CLAUDE.md` from the project root and parent directories. This is how you give Claude project-specific instructions that persist across sessions.
Create one at the project root:
```bash
echo "# Project Instructions\nAlways use TypeScript strict mode." > CLAUDE.md
```
On Tabitha, Silma's workspace CLAUDE.md equivalent is `AGENTS.md`.
---
## Using Local LLMs with Claude Code
Claude Code supports OpenAI-compatible third-party providers. Point it at the local llama.cpp server:
```bash
# Set provider to local llama.cpp (Gemma models on Tabitha)
export ANTHROPIC_BASE_URL=http://localhost:8080/v1
export ANTHROPIC_API_KEY=local # required but ignored by llama.cpp
claude --model gemma-4-e4b
```
See `tools/local-llm.llm.md` for full local LLM details.
---
## Environment in This Workspace
| Detail | Value |
|--------|-------|
| **Workspace** | `/Users/Tabitha/.openclaw/workspace/` |
| **OCPlatform channel** | webchat (main session) |
| **Model** | `anthropic/claude-sonnet-4-6` (check `/status`) |
| **Agent YAML** | `AGENTS.md` at workspace root |
| **Memory** | `memory/YYYY-MM-DD.md` (daily) + `MEMORY.md` (long-term) |
---
## Tips for This Environment
- `Glob` and `Grep` built-in tools are **not available** in OCPlatform sessions — use `Bash` with `find`/`grep` instead
- For cross-machine work, use the kittens WebSocket bridge (see `tools/tailscale.llm.md`)
- Run `source credentials/secrets.env` inside Bash tool calls to load credentials
- k8s MCPs require port-forward — run `bash k8s/silma-ai/scripts/port-forward.sh` first
tools/codex-cli.md
+151
View File
@@ -0,0 +1,151 @@
# Codex CLI Guide
Codex CLI is OpenAI's lightweight local coding agent. It runs in your terminal, reads your codebase, edits files, and executes commands. Part of ChatGPT Plus/Pro/Business plans or usable with an API key.
**Official docs:** https://developers.openai.com/codex
**GitHub:** https://github.com/openai/codex
---
## Installation
```bash
# macOS / Linux (recommended)
curl -fsSL https://chatgpt.com/codex/install.sh | sh
# Homebrew
brew install --cask codex
# npm (global)
npm install -g @openai/codex
# Windows PowerShell
powershell -ExecutionPolicy ByPass -c "irm https://chatgpt.com/codex/install.ps1 | iex"
```
---
## Authentication
```bash
codex # On first run, select "Sign in with ChatGPT"
```
**With API key instead:**
```bash
export OPENAI_API_KEY=sk-...
codex
```
For full auth options: https://developers.openai.com/codex/auth
---
## Basic Usage
```bash
# Start interactive session in current directory
codex
# One-shot task (non-interactive)
codex "add input validation to the login form"
# Quiet mode (minimal output)
codex -q "fix the TypeScript errors"
# Full auto mode (no confirmations — use carefully)
codex --approval-mode full-auto "refactor the API layer"
```
---
## Approval Modes
| Mode | Behavior |
|------|----------|
| `suggest` (default) | Shows proposed changes, waits for approval |
| `auto-edit` | Edits files automatically, asks before shell commands |
| `full-auto` | Runs everything without asking (use in sandboxed environments) |
```bash
codex --approval-mode auto-edit "clean up unused imports"
codex --approval-mode full-auto "run tests and fix failures"
```
---
## Key Flags
| Flag | Description |
|------|-------------|
| `--model <model>` | Specify model (`o4-mini`, `o3`, etc.) |
| `--approval-mode <mode>` | Set approval level |
| `-q` / `--quiet` | Minimal output |
| `--no-project-doc` | Ignore `AGENTS.md` / `CODEX.md` |
| `--project-doc <file>` | Use custom instructions file |
| `--full-stdout` | Show all shell output (not truncated) |
---
## AGENTS.md / CODEX.md (Project Instructions)
Codex automatically reads `AGENTS.md` from the project root (and parent directories). Put project-specific instructions there:
```markdown
# Project Instructions
- Use TypeScript strict mode
- Run `npm test` to verify changes
- Never modify files in /dist directly
```
In this environment, `AGENTS.md` is already used by Silma's workspace. For a client project, create one in the repo root.
---
## Using with Local LLMs
Codex CLI supports OpenAI-compatible endpoints:
```bash
# Point at local llama.cpp (Gemma models on Tabitha)
OPENAI_BASE_URL=http://localhost:8080/v1 \
OPENAI_API_KEY=local \
codex --model gemma-4-e4b "explain this codebase"
```
See `tools/local-llm.llm.md` for available local models and endpoints.
---
## Working with This Environment
```bash
# Clone from Gitea first, then run codex in the repo
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cd aarete-doczyai-app
codex
# Load credentials before running if the task touches AWS/GitHub
source /Users/Tabitha/.openclaw/workspace/credentials/secrets.env
codex "deploy the latest build to Amplify"
```
---
## IDE Integration
Codex also works as a VS Code / Cursor / Windsurf extension:
```
VS Code: https://marketplace.visualstudio.com/items?itemName=OpenAI.codex
Cursor: Install from Cursor extensions panel (search "Codex")
```
---
## Tips
- Start with `suggest` mode to review changes before they land
- Use `full-auto` only in throwaway branches or sandboxed environments
- For long-running tasks, use the Codex web app at https://chatgpt.com/codex (cloud-based, parallel agents)
- Codex reads `AGENTS.md` — keep it concise and action-oriented
tools/cursor-cli.md
+167
View File
@@ -0,0 +1,167 @@
# Cursor CLI & IDE Guide
Cursor is an AI-first code editor (fork of VS Code) with deep agent, inline edit, and multi-file reasoning capabilities. It runs as a desktop IDE with a companion CLI for opening projects from the terminal.
**Official docs:** https://docs.cursor.com
**Download:** https://www.cursor.com/download
---
## Installation
```bash
# macOS (download .dmg from cursor.com, or via Homebrew)
brew install --cask cursor
# The `cursor` CLI is installed automatically with the desktop app
# macOS: add to PATH via Command Palette → "Install 'cursor' command in PATH"
```
**Installed on:** Tabitha (and any machine with Cursor desktop app)
---
## CLI Usage
```bash
# Open current directory in Cursor
cursor .
# Open a specific file or folder
cursor /path/to/project
cursor src/components/Button.tsx
# Open a Gitea-cloned repo
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cursor aarete-doczyai-app/
# Reuse existing window
cursor --reuse-window .
# New window
cursor --new-window .
```
---
## Agent Mode
Cursor's Agent mode (formerly Composer) lets you give multi-step tasks in natural language. It reads and edits across files, runs terminal commands, and can loop until the task is done.
**Open Agent:** `Cmd+I` (or `Ctrl+I` on Windows/Linux)
```
# Example agent prompts:
"Add form validation to the login page and write tests for it"
"Refactor the API calls to use a centralized fetch wrapper"
"Fix all TypeScript errors in the project"
```
---
## Inline Edit
Quick single-location edits without opening Agent:
**Trigger:** `Cmd+K` on selected code
```
# Example inline prompts:
"Add error handling"
"Convert to async/await"
"Add JSDoc comment"
```
---
## Rules (Project Instructions)
Cursor reads `.cursorrules` (legacy) or `cursor/rules/` directory for project-specific AI instructions. These persist across sessions and shape how the AI behaves in your codebase.
**Create `.cursorrules` at project root:**
```
# aarete-doczyai-app Cursor Rules
- TypeScript strict mode is required
- Use React functional components with hooks only
- API calls go through lib/api — never fetch() directly in components
- Run `npm run lint && npm run test:ci` before considering a task done
- This project is on a local Gitea: http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app
```
---
## MCP in Cursor
Cursor supports MCP servers for extending AI capabilities. Configure in `~/.cursor/mcp.json` or via Settings → MCP.
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "<your-pat>" }
},
"postgres": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://postgres:pass@127.0.0.1:5432/silma"]
}
}
}
```
---
## Using Local LLMs in Cursor
Cursor supports custom OpenAI-compatible model endpoints:
1. Open **Settings → Models → Add Model**
2. Set base URL to `http://localhost:8080/v1` (Gemma-4-E4B) or `http://localhost:8081/v1` (Gemma-4-26B)
3. Set API key to `local` (required but ignored by llama.cpp)
4. Name the model `gemma-4-e4b` or `gemma-4-26b`
See `tools/local-llm.llm.md` for full local LLM details and endpoints.
---
## Useful Keyboard Shortcuts
| Action | macOS | Windows/Linux |
|--------|-------|---------------|
| Open Agent | `Cmd+I` | `Ctrl+I` |
| Inline Edit | `Cmd+K` | `Ctrl+K` |
| Chat panel | `Cmd+L` | `Ctrl+L` |
| Command Palette | `Cmd+Shift+P` | `Ctrl+Shift+P` |
| Terminal | `` Ctrl+` `` | `` Ctrl+` `` |
| File search | `Cmd+P` | `Ctrl+P` |
| Symbol search | `Cmd+T` | `Ctrl+T` |
---
## Working with Gitea Repos in Cursor
```bash
# Clone from local Gitea
git clone http://jacob-mathison:<PAT>@100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cursor aarete-doczyai-app/
# Or clone first, configure remote without PAT in URL
git clone http://100.79.253.19:3000/jacob-mathison/aarete-doczyai-app.git
cd aarete-doczyai-app
git config credential.helper store
cursor .
```
Cursor's Source Control panel works with local Gitea repos the same as GitHub — commit, push, pull, branch all work normally.
---
## Tips for This Environment
- The Claude Code extension for Cursor is available: search "Claude Code" in Extensions (`Cmd+Shift+X`)
- For AI-heavy tasks, Agent mode + a good `.cursorrules` file beats ad-hoc prompts every time
- Cursor indexes your codebase on first open — give it a minute on large repos
- Use `@file`, `@folder`, `@symbol` mentions in Agent to scope context precisely
- `@docs` lets you pull in external documentation URLs as context mid-chat
tools/local-llm.llm.md
+170
View File
@@ -0,0 +1,170 @@
# Local LLM Guide
Two LLM models run locally on Tabitha via llama.cpp with Metal (Apple Silicon GPU) acceleration. Both expose OpenAI-compatible REST APIs — drop-in replacements for `api.openai.com` endpoints.
**llama.cpp GitHub:** https://github.com/ggml-org/llama.cpp
**llama.cpp API docs:** https://github.com/ggml-org/llama.cpp/blob/master/tools/server/README.md
---
## Running the Servers
```bash
cd /Users/Tabitha/.openclaw
npm run api:llm
```
This starts both models in the background. Logs go to stdout/stderr.
---
## Models
### Gemma-4-E4B — Fast / Light
| Field | Value |
|-------|-------|
| **Model** | Google Gemma 4 E4B (4-billion parameter, efficient variant) |
| **Endpoint** | `http://localhost:8080` |
| **API** | OpenAI-compatible (`/v1/chat/completions`, `/v1/completions`, `/v1/models`) |
| **Use case** | Quick tasks, code generation, summarization — fast response |
| **Acceleration** | Apple Metal (GPU) |
### Gemma-4-26B — Capable / Reasoning
| Field | Value |
|-------|-------|
| **Model** | Google Gemma 4 27B |
| **Endpoint** | `http://localhost:8081` |
| **API** | OpenAI-compatible |
| **Use case** | Complex reasoning, architecture questions, longer context tasks |
| **Acceleration** | Apple Metal (GPU) |
---
## API Usage
Both models speak the OpenAI API format:
```bash
# Chat completion — Gemma-4-E4B (fast)
curl -s http://localhost:8080/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gemma-4-e4b",
"messages": [{"role": "user", "content": "Explain this code: ..."}]
}' | python3 -m json.tool
# Chat completion — Gemma-4-26B (capable)
curl -s http://localhost:8081/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "gemma-4-26b",
"messages": [{"role": "user", "content": "Design a REST API for..."}]
}' | python3 -m json.tool
# List available models
curl -s http://localhost:8080/v1/models
curl -s http://localhost:8081/v1/models
```
---
## Python (openai SDK)
```python
from openai import OpenAI
# Fast model
fast = OpenAI(base_url="http://localhost:8080/v1", api_key="local")
response = fast.chat.completions.create(
model="gemma-4-e4b",
messages=[{"role": "user", "content": "Write a Python function to..."}]
)
print(response.choices[0].message.content)
# Capable model
smart = OpenAI(base_url="http://localhost:8081/v1", api_key="local")
response = smart.chat.completions.create(
model="gemma-4-26b",
messages=[{"role": "user", "content": "Architect a microservice system for..."}],
temperature=0.7,
max_tokens=2048
)
print(response.choices[0].message.content)
```
---
## Using with AI Coding Tools
### Claude Code CLI
```bash
export ANTHROPIC_BASE_URL=http://localhost:8080/v1
export ANTHROPIC_API_KEY=local
claude --model gemma-4-e4b
```
### Codex CLI
```bash
OPENAI_BASE_URL=http://localhost:8080/v1 \
OPENAI_API_KEY=local \
codex --model gemma-4-e4b "explain this codebase"
```
### Cursor (IDE)
Settings → Models → Add Model:
- Base URL: `http://localhost:8080/v1`
- API Key: `local`
- Model name: `gemma-4-e4b`
Repeat for port 8081 / `gemma-4-26b`.
### LangChain / any OpenAI-compatible client
```python
from langchain_openai import ChatOpenAI
llm = ChatOpenAI(
base_url="http://localhost:8080/v1",
api_key="local",
model="gemma-4-e4b"
)
```
---
## Health Check
```bash
# Check if servers are responding
curl -s http://localhost:8080/health && echo " — E4B OK"
curl -s http://localhost:8081/health && echo " — 26B OK"
# Or check model list
curl -s http://localhost:8080/v1/models | python3 -c "import sys,json; [print(m['id']) for m in json.load(sys.stdin)['data']]"
```
---
## Model Storage
Models are stored on Theodora (hot SSD cache):
```
~/.cache/huggingface → /Volumes/Theodora/models/huggingface (symlink)
~/.cache/llama.cpp → /Volumes/Theodora/models/llama-cpp (symlink)
```
Archive copies on Hagia:
```
/Volumes/Hagia/models/huggingface/
/Volumes/Hagia/models/llama-cpp/
```
---
## Notes for AI Agents
- The servers run **on the host** (not in Docker/k8s) — they are accessible from any process on Tabitha
- Theodora (SSD) must be mounted for fast model loading — `ls /Volumes/Theodora` to verify
- If a server is not responding, run `cd /Users/Tabitha/.openclaw && npm run api:llm` to start it
- **Gemma-4-E4B** is the default fast option — use it for code tasks, summarization, quick Q&A
- **Gemma-4-26B** costs more compute — use it for complex reasoning, architecture, long context
- Both are private and local — no data leaves the machine