snipara-companion 0.1.2 → 0.2.0

package/README.md

@@ -1,22 +1,27 @@
 # snipara-companion
 
-Legacy hook-oriented CLI package kept in the monorepo for older `rlm-hook` workflows.
+`snipara-companion` is Snipara's local companion CLI.
 
-Current automation source-of-truth docs are:
+In this repository, the source currently lives in `packages/cli`, and the installed executable is `rlm-hook`.
 
-- `docs/guides/AUTOMATION_HOOKS.md`
-- `docs/guides/OPENCLAW_HOOKS.md`
-- `docs/operations/REPO_CHANGES_AND_AUTOMATIONS.md`
+This package complements `snipara-mcp`. It does not replace it.
 
-The local CLI also acts as an optional thin companion for common hosted workflows such as
-querying context, generating plans, uploading docs, fetching chunks, bootstrapping sessions, and
-committing end-of-task outcomes.
+## When To Use It
 
-For workflow commands, the CLI now treats durable memory and short-lived session context as
-separate lanes. `session-bootstrap` loads durable memory by default and only includes transient
-carryover when you ask for it explicitly.
+| If you need...                                            | Install...               |
+| --------------------------------------------------------- | ------------------------ |
+| MCP tools, OAuth login, project-scoped context and memory | `snipara-mcp`            |
+| One-command setup for `snipara-mcp` + `rlm-runtime`       | `create-snipara`         |
+| Optional local helper CLI and hook-oriented automation    | `snipara-companion`      |
+| OpenClaw-specific automation hooks                        | `snipara-openclaw-hooks` |
 
-The current hosted API base is `https://api.snipara.com`.
+### Codex Note
+
+For Codex, the primary integration remains `mcp.json` plus `AGENTS.md`.
+
+- `snipara-companion` is optional for Codex.
+- This package does not currently scaffold a Codex-specific preset.
+- Use it for shared local helper workflows only when that is explicitly useful.
 
 ## Installation
 
@@ -28,108 +33,52 @@ pnpm add -g snipara-companion
 yarn global add snipara-companion
 ```
 
-## Quick Start
-
-### 1. Initialize Configuration
+## Installed Command
 
 ```bash
-rlm-hook init
+rlm-hook
 ```
 
-This interactive setup will:
-
-- Prompt for your RLM API key
-- Prompt for your project ID
-- Configure the API URL (default: https://api.snipara.com)
-- Generate Claude Code hook configuration
-
-### 2. Configure Claude Code Hooks
-
-The `init` command generates a `.claude/settings.json` file. Copy the hooks configuration to your Claude Code settings:
-
-```json
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Read|Grep|Glob",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "rlm-hook pre-tool \"$TOOL_INPUT\""
-          }
-        ]
-      }
-    ],
-    "PostToolUse": [
-      {
-        "matcher": "Read|Edit|Write",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "rlm-hook post-tool \"$TOOL_INPUT\""
-          }
-        ]
-      }
-    ],
-    "Stop": [
-      {
-        "matcher": ".*",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "rlm-hook session-end"
-          }
-        ]
-      }
-    ]
-  }
-}
-```
+## New In 0.2.0
 
-Note: Claude SessionStart hooks require `jq` to format the hook output JSON.
+- direct `rlm-hook code` access for `callers`, `imports`, `neighbors`, and `shortest-path`
+- `workflow run --mode auto|full|orchestrate` for hosted-first workflow routing
+- `rlm-hook shared-context` for project-linked standards and team guidance
+- automatic fallback to project token auth when a stale `SNIPARA_API_KEY` overrides a valid local login
 
-### Cursor Hooks
+## Supported Client Presets Today
 
-```bash
-rlm-hook init --with-hooks --client cursor
-```
+The built-in `init` flow currently supports:
 
-Creates:
+- `claude-code`
+- `cursor`
+- `windsurf`
 
-- `.cursor/hooks.json`
-- `.cursor/hooks/preCompact.sh`
-- `.cursor/hooks/sessionStart.sh`
-- `.cursor/hooks/beforeReadFile.sh`
-- `.cursor/hooks/afterFileEdit.sh`
+## Quick Start
 
-### Windsurf Hooks
+### Claude Code
 
 ```bash
-rlm-hook init --with-hooks --client windsurf
+rlm-hook init --with-hooks --client claude-code
 ```
 
-Creates:
-
-- `.windsurf/cascade-hooks.json`
-- `.windsurf/hooks/pre-read.sh`
-- `.windsurf/hooks/post-read.sh`
-- `.windsurf/hooks/post-write.sh`
+### Cursor
 
-### 3. Start Using RLM
+```bash
+rlm-hook init --with-hooks --client cursor
+```
 
-Your Claude Code sessions will now automatically:
+### Windsurf
 
-- Query RLM for relevant context before file operations
-- Track which files are accessed during the session
-- Emit canonical automation events for hook activity
-- Persist session context when the conversation ends
+```bash
+rlm-hook init --with-hooks --client windsurf
+```
 
 ## Commands
 
 ### `rlm-hook init`
 
-Interactive setup wizard for configuring RLM integration.
+Initialize local configuration and optionally generate client hook files.
 
 ```bash
 rlm-hook init
@@ -139,69 +88,43 @@ Options:
 
 - `--api-key <key>` - Skip prompt for API key
 - `--project-id <id>` - Skip prompt for project ID
-- `--client <client>` - Client type (`claude-code`, `cursor`, `windsurf`)
+- `--client <client>` - `claude-code`, `cursor`, or `windsurf`
 - `--with-hooks` - Install hooks automatically
-- `--dir <directory>` - Project directory for hooks (default: current)
-
-Examples:
-
-```bash
-rlm-hook init --with-hooks --client claude-code
-rlm-hook init --with-hooks --client cursor
-rlm-hook init --with-hooks --client windsurf
-```
+- `--force` - Overwrite existing generated files
+- `--dir <directory>` - Target directory for generated files
 
 ### `rlm-hook config`
 
-Display current configuration.
+Show the current configuration.
 
 ```bash
 rlm-hook config
 ```
 
-### `rlm-hook pre-tool <input>`
+### `rlm-hook pre-tool`
 
-PreToolUse hook handler. Called before Read/Grep/Glob operations.
+Resolve a query from tool input and fetch relevant context.
 
 ```bash
-rlm-hook pre-tool '{"path": "/src/api/auth.ts"}'
+rlm-hook pre-tool '{"path":"/src/api/auth.ts"}'
 ```
 
-Features:
-
-- Queries RLM for relevant context based on the file/search
-- Uses a workspace-scoped disk cache with TTL, LRU trimming, and nearby-query reuse
-- Emits a `tool_call` automation event for hook telemetry
-- Returns optimized context as a system message
+### `rlm-hook post-tool`
 
-### `rlm-hook post-tool <input>`
-
-PostToolUse hook handler. Called after Read/Edit/Write operations.
+Track file access for the current session.
 
 ```bash
-rlm-hook post-tool '{"file_path": "/src/api/auth.ts"}'
+rlm-hook post-tool '{"file_path":"/src/api/auth.ts"}'
 ```
 
-Features:
-
-- Tracks accessed files for session persistence
-- Emits a `tool_result` automation event with tracked files
-- Non-blocking - doesn't slow down your workflow
-
 ### `rlm-hook session-end`
 
-Stop hook handler. Called when Claude Code session ends.
+Persist the current session.
 
 ```bash
 rlm-hook session-end
 ```
 
-Features:
-
-- Emits a `session_end` automation event
-- Persists session context to RLM
-- Leaves the local cache available for future hook hits
-
 ### `rlm-hook session status`
 
 Show current session information.
@@ -212,7 +135,7 @@ rlm-hook session status
 
 ### `rlm-hook session reset`
 
-Reset session and start fresh.
+Start a new session ID locally.
 
 ```bash
 rlm-hook session reset
@@ -237,6 +160,13 @@ These are thin local wrappers around hosted Snipara workflows:
 
 ```bash
 rlm-hook query --query "auth middleware"
+rlm-hook query --query "who calls src.rlm_engine.RLMEngine._handle_context_query" --follow-recommendation
+rlm-hook workflow run --mode auto --query "who imports src.rlm_engine"
+rlm-hook workflow run --mode full --include-session-context --query "plan the auth refactor"
+rlm-hook code callers --qualified-name src.rlm_engine.RLMEngine._handle_context_query
+rlm-hook code imports --file-path src/rlm_engine.py
+rlm-hook code neighbors --qualified-name src.rlm_engine.RLMEngine._handle_context_query
+rlm-hook code shortest-path --from src.rlm_engine.RLMEngine._handle_multi_query.execute_single_query --to src.rlm_engine.RLMEngine._handle_context_query
 rlm-hook plan --query "implement OAuth device flow"
 rlm-hook upload --path docs/spec.md --file ./docs/spec.md
 rlm-hook chunk get --chunk-id chunk_123
@@ -254,6 +184,11 @@ hosted response.
 
 Semantics:
 
+- `rlm-hook query --follow-recommendation` = execute the hosted recommended structural tool instead of only printing it
+- `rlm-hook workflow run --mode auto` = context query plus automatic `rlm_code_*` follow-up when Snipara recommends one
+- `rlm-hook workflow run --mode full` = session bootstrap + context query + automatic structural follow-up + hosted plan
+- `rlm-hook workflow run --mode orchestrate` = explicit hosted orchestrator flow for deeper multi-step exploration
+- `rlm-hook code *` = direct access to the code graph tools without routing through `rlm_context_query`
 - `rlm-hook session-bootstrap` = durable memory first, optional weak session carryover second
 - `rlm-hook task-commit` = durable outcomes only
 - `--max-daily-tokens` is still accepted as a compatibility alias for `--max-context-tokens`
@@ -269,7 +204,7 @@ To test a packed tarball manually, use `npm exec --package`:
 
 ```bash
 npm pack
-npm exec --package ./snipara-companion-0.1.1.tgz rlm-hook -- --help
+npm exec --package ./snipara-companion-0.2.0.tgz rlm-hook -- --help
 ```
 
 Do not use `npx /path/to/snipara-companion-*.tgz`. npm will try to execute the tarball itself instead of
@@ -279,6 +214,9 @@ Design rule:
 
 - local CLI = workflow facade
 - hosted Snipara = source of truth for context, chunks, plans, memory, and review policy
+- use `companion` for daily coding ergonomics and auto-routing
+- use `orchestrate` only when the task is genuinely multi-step and exploration-heavy
+- use `snipara-orchestrator` only for proof-based validation, drift detection, and production gates
 
 ### `rlm-hook cache clear`
 
@@ -288,184 +226,17 @@ Clear the local query cache.
 rlm-hook cache clear
 ```
 
-## Configuration
-
-Configuration is stored at `~/.rlmsaas/config.json`:
-
-```json
-{
-  "apiKey": "rlm_your_api_key",
-  "projectId": "proj_abc123",
-  "apiUrl": "https://api.snipara.com",
-  "sessionId": "session_xyz789"
-}
-```
-
-### Environment Variables
-
-You can also use environment variables:
-
-| Variable             | Description                   |
-| -------------------- | ----------------------------- |
-| `SNIPARA_API_KEY`    | API key (overrides config)    |
-| `SNIPARA_PROJECT_ID` | Project ID (overrides config) |
-| `SNIPARA_API_URL`    | API URL (overrides config)    |
-
-## How It Works
-
-### PreToolUse Hook
-
-When Claude Code is about to read a file or search the codebase:
-
-1. The hook extracts the file path or search query
-2. Queries RLM for relevant documentation context
-3. Returns context that's injected into Claude's system message
-4. Results are cached locally per workspace, with exact and nearby-query reuse
-
-```
-┌─────────────────────────────────────────────┐
-│  Claude Code: "Let me read auth.ts..."      │
-├─────────────────────────────────────────────┤
-│  rlm-hook pre-tool                          │
-│  ├─ Extract: "auth.ts"                      │
-│  ├─ Check cache: miss                       │
-│  ├─ Query RLM: "authentication auth.ts"     │
-│  └─ Return: Relevant docs + standards       │
-├─────────────────────────────────────────────┤
-│  Claude: Reads file WITH context            │
-└─────────────────────────────────────────────┘
-```
-
-### PostToolUse Hook
-
-After Claude Code reads or modifies a file:
-
-1. The hook extracts the file path
-2. Tracks the file in the current session
-3. Non-blocking - returns immediately
-
-### Stop Hook
-
-When the Claude Code session ends:
-
-1. Persists all tracked files to RLM
-2. Allows future sessions to pick up context
-3. Clears local cache
-
-## Caching
-
-The CLI includes a local cache to minimize API calls:
-
-- **Cache Location**: `~/.rlmsaas/cache/context-v2/`
-- **TTL**: 15 minutes per query by default
-- **Scope**: Workspace root + project ID + query options
-- **Reuse**: Exact hits first, then nearby queries in the same workspace, then session bootstrap warm context
-- **Bootstrap source split**: Warm snapshots can include durable memory plus optional session context
-- **Eviction**: LRU trimming with a persistent index
-
-Clear the cache manually:
-
-```bash
-rlm-hook cache clear
-```
-
-## API Integration
-
-The CLI communicates with these RLM endpoints:
-
-| Endpoint                                  | Purpose              |
-| ----------------------------------------- | -------------------- |
-| `POST /api/v1/:projectId/context`         | Query for context    |
-| `POST /api/v1/:projectId/session/track`   | Track accessed files |
-| `POST /api/v1/:projectId/session/persist` | Persist session      |
-| `GET /api/v1/:projectId/health`           | Test connection      |
-
-## Troubleshooting
-
-### "API key not configured"
-
-Run `rlm-hook init` to set up your configuration.
-
-### "Project ID not configured"
-
-Run `rlm-hook init` or set the `RLM_PROJECT_ID` environment variable.
-
-### "Connection timeout"
-
-1. Check your internet connection
-2. Verify the API URL is correct
-3. Check RLM service status
-
-### "Invalid API key"
-
-1. Verify your API key in the RLM dashboard
-2. Ensure the key hasn't been revoked
-3. Check the key has access to the project
-
-### Hook not triggering
-
-1. Verify hooks are configured in `.claude/settings.json`
-2. Check the hook matcher patterns
-3. Ensure `rlm-hook` is in your PATH
-
-### "CLI usage/help printed during hooks"
-
-1. Ensure the hook command includes tool input: `rlm-hook pre-tool "$TOOL_INPUT"`
-2. Confirm the matcher targets the right tools (Read/Grep/Glob or Read/Edit/Write)
-3. Restart Claude Code after updating `.claude/settings.json`
-
-### "Files not tracked after edits"
-
-1. Confirm `PostToolUse` is configured for `Read|Edit|Write`
-2. Verify the hook calls `rlm-hook post-tool "$TOOL_INPUT"`
-3. Run with debug output: `RLM_DEBUG=1 rlm-hook post-tool '{"file_path":"file.ts"}'`
-
-### "Need more debug output"
-
-Set `RLM_DEBUG=1` to surface hook errors on stderr.
-
-### Cache issues
-
-Clear the cache and try again:
-
-```bash
-rlm-hook cache clear
-```
-
-## Development
-
-### Building
-
-```bash
-cd packages/cli
-pnpm install
-pnpm build
-```
-
-### Testing locally
-
-```bash
-pnpm dev  # Watch mode
-node dist/index.js init
-```
-
-### Running tests
-
-```bash
-pnpm test
-```
-
-## Requirements
+## Positioning
 
-- Node.js 18 or later
-- Claude Code (or compatible MCP client)
-- RLM SaaS account with API key
+- Use `snipara-mcp` as the main Snipara client surface.
+- Use `snipara-companion` when you want local helper behavior around supported hook clients.
+- Do not imply that every Snipara installation needs this package.
 
-## Related
+## Related Packages
 
-- [RLM SaaS Documentation](https://docs.rlm.dev)
-- [Claude Code Hooks](https://docs.claude.ai/claude-code/hooks)
-- [MCP Protocol](https://modelcontextprotocol.io)
+- `snipara-mcp` - core MCP client
+- `create-snipara` - onboarding for `snipara-mcp` + `rlm-runtime`
+- `snipara-openclaw-hooks` - OpenClaw-specific automation hooks
 
 ## License