@indiccoder/mentis-cli 1.1.3 → 1.1.5

package/.mentis/sessions/1769881926630.json

@@ -0,0 +1,57 @@
+{
+  "timestamp": 1769881926630,
+  "name": "session-1769881926630",
+  "history": [
+    {
+      "role": "user",
+      "content": "Repository Structure:\n├── .claude/\n│   └── settings.local.json\n├── .mentis/\n│   ├── commands/\n│   │   └── ls.md\n│   ├── sessions/\n│   │   ├── 1769189035730.json\n│   │   ├── 1769189569160.json\n│   │   ├── 1769767538672.json\n│   │   ├── 1769767785155.json\n│   │   ├── 1769768745802.json\n│   │   ├── 1769769600884.json\n│   │   ├── 1769770030160.json\n│   │   ├── 1769770606004.json\n│   │   └── 1769771084515.json\n│   └── session.json\n├── docs/\n│   └── SKILLS.md\n├── examples/\n│   └── skills/\n│       ├── code-reviewer/\n│       │   └── SKILL.md\n│       ├── commit-helper/\n│       │   └── SKILL.md\n│       └── pdf-processing/\n│           └── SKILL.md\n├── scripts/\n│   ├── test_config_update.ts\n│   ├── test_features.ts\n│   ├── test_glm.ts\n│   └── test_models.ts\n├── src/\n│   ├── checkpoint/\n│   │   └── CheckpointManager.ts\n│   ├── commands/\n│   │   ├── __tests__/\n│   │   │   └── CommandManager.test.ts\n│   │   ├── Command.ts\n│   │   ├── CommandCreator.ts\n│   │   ├── CommandManager.ts\n│   │   └── SlashCommandTool.ts\n│   ├── config/\n│   │   └── ConfigManager.ts\n│   ├── context/\n│   │   ├── ContextManager.ts\n│   │   └── RepoMapper.ts\n│   ├── llm/\n│   │   ├── ModelInterface.ts\n│   │   └── OpenAIClient.ts\n│   ├── mcp/\n│   │   ├── JsonRpcClient.ts\n│   │   └── McpClient.ts\n│   ├── repl/\n│   │   ├── PersistentShell.ts\n│   │   └── ReplManager.ts\n│   ├── skills/\n│   │   ├── __tests__/\n│   │   │   └── SkillsManager.test.ts\n│   │   ├── LoadSkillTool.ts\n│   │   ├── Skill.ts\n│   │   ├── SkillCreator.ts\n│   │   └── SkillsManager.ts\n│   ├── tools/\n│   │   ├── FileTools.ts\n│   │   ├── GitTools.ts\n│   │   ├── PersistentShellTool.ts\n│   │   ├── SearchTools.ts\n│   │   ├── Tool.ts\n│   │   └── WebSearchTool.ts\n│   ├── ui/\n│   │   ├── InputBox.ts\n│   │   └── UIManager.ts\n│   ├── utils/\n│   │   ├── __mocks__/\n│   │   │   └── chalk.ts\n│   │   ├── __tests__/\n│   │   │   └── ContextVisualizer.test.ts\n│   │   ├── ContextVisualizer.ts\n│   │   ├── ConversationCompacter.ts\n│   │   ├── ProjectInitializer.ts\n│   │   └── UpdateManager.ts\n│   ├── debug_google.ts\n│   ├── debug_lite_headers.ts\n│   ├── debug_lite.ts\n│   ├── debug_search.ts\n│   └── index.ts\n├── .gitignore\n├── ARCHITECTURE.md\n├── CONTRIBUTING.md\n├── debug_fs.js\n├── google_dump.html\n├── lite_dump.html\n├── lite_headers_dump.html\n├── package-lock.json\n├── package.json\n├── README.md\n├── screenshot_1765779883482_9b30.png\n└── tsconfig.json\n\n\n\n\nUser Question: Available Custom Commands:\n/ls [directory]: List all files in current directory\n\nhi do you have mcp capability\n[SYSTEM: You are in BUILD mode. Focus on implementing working code that solves the user request efficiently.]"
+    },
+    {
+      "role": "assistant",
+      "content": "\nYes, I do have MCP (Model Context Protocol) capability! Looking at the repository structure, I can see there's a dedicated MCP implementation in the `src/mcp/` directory with:\n\n- `JsonRpcClient.ts` - Handles JSON-RPC communication\n- `McpClient.ts` - Main MCP client implementation\n\nThe MCP system allows for integrating external tools and services through a standardized protocol. Let me check what MCP functionality is currently available:\n",
+      "tool_calls": [
+        {
+          "function": {
+            "arguments": "{\"filePath\":\"src/mcp/McpClient.ts\"}",
+            "name": "read_file"
+          },
+          "id": "call_-7937540705308331019",
+          "index": 0,
+          "type": "function"
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_-7937540705308331019",
+      "name": "read_file",
+      "content": "import { JsonRpcClient } from './JsonRpcClient';\r\nimport { Tool } from '../tools/Tool';\r\n\r\nexport class McpClient {\r\n    private rpc: JsonRpcClient;\r\n    public serverName: string = 'unknown';\r\n\r\n    constructor(command: string, args: string[]) {\r\n        this.rpc = new JsonRpcClient(command, args);\r\n    }\r\n\r\n    async initialize() {\r\n        const result = await this.rpc.sendRequest('initialize', {\r\n            protocolVersion: '2024-11-05',\r\n            capabilities: {},\r\n            clientInfo: {\r\n                name: 'mentis-cli',\r\n                version: '1.0.0',\r\n            },\r\n        });\r\n\r\n        this.serverName = result.serverInfo.name;\r\n\r\n        // Notify initialized\r\n        this.rpc.sendNotification('notifications/initialized');\r\n        return result;\r\n    }\r\n\r\n    async listTools(): Promise<Tool[]> {\r\n        const result = await this.rpc.sendRequest('tools/list');\r\n        const mcpTools = result.tools || [];\r\n\r\n        return mcpTools.map((t: any) => new McpToolAdapter(this, t));\r\n    }\r\n\r\n    async callTool(name: string, args: any): Promise<any> {\r\n        return this.rpc.sendRequest('tools/call', {\r\n            name,\r\n            arguments: args,\r\n        });\r\n    }\r\n\r\n    disconnect() {\r\n        this.rpc.disconnect();\r\n    }\r\n}\r\n\r\nclass McpToolAdapter implements Tool {\r\n    private client: McpClient;\r\n    public name: string;\r\n    public description: string;\r\n    public parameters: any;\r\n\r\n    constructor(client: McpClient, toolDef: any) {\r\n        this.client = client;\r\n        this.name = toolDef.name;\r\n        this.description = toolDef.description || '';\r\n        this.parameters = toolDef.inputSchema || {};\r\n    }\r\n\r\n    async execute(args: any): Promise<string> {\r\n        const result = await this.client.callTool(this.name, args);\r\n        // MCP returns { content: [ { type: 'text', text: '...' } ], isError: boolean }\r\n        if (result.isError) {\r\n            throw new Error('MCP Tool Error');\r\n        }\r\n\r\n        // Extract text content\r\n        if (result.content && Array.isArray(result.content)) {\r\n            return result.content.map((c: any) => c.text).join('\\n');\r\n        }\r\n\r\n        return JSON.stringify(result);\r\n    }\r\n}\r\n"
+    },
+    {
+      "role": "assistant",
+      "content": "\n",
+      "tool_calls": [
+        {
+          "function": {
+            "arguments": "{\"filePath\":\"src/mcp/JsonRpcClient.ts\"}",
+            "name": "read_file"
+          },
+          "id": "call_-7937555136399364450",
+          "index": 0,
+          "type": "function"
+        }
+      ]
+    },
+    {
+      "role": "tool",
+      "tool_call_id": "call_-7937555136399364450",
+      "name": "read_file",
+      "content": "import { spawn, ChildProcess } from 'child_process';\r\nimport * as readline from 'readline';\r\n\r\nexport interface JsonRpcRequest {\r\n    jsonrpc: '2.0';\r\n    method: string;\r\n    params?: any;\r\n    id?: number | string;\r\n}\r\n\r\nexport interface JsonRpcResponse {\r\n    jsonrpc: '2.0';\r\n    id: number | string | null;\r\n    result?: any;\r\n    error?: {\r\n        code: number;\r\n        message: string;\r\n        data?: any;\r\n    };\r\n}\r\n\r\nexport class JsonRpcClient {\r\n    private process: ChildProcess;\r\n    private sequence = 0;\r\n    private pendingRequests = new Map<number | string, { resolve: Function; reject: Function }>();\r\n\r\n    constructor(command: string, args: string[]) {\r\n        this.process = spawn(command, args, {\r\n            stdio: ['pipe', 'pipe', 'inherit'], // stdin, stdout, stderr\r\n        });\r\n\r\n        if (!this.process.stdout) {\r\n            throw new Error('Failed to open stdout for MCP process');\r\n        }\r\n\r\n        const rl = readline.createInterface({ input: this.process.stdout });\r\n        rl.on('line', (line) => this.handleMessage(line));\r\n\r\n        this.process.on('error', (err) => console.error('MCP Process Error:', err));\r\n        this.process.on('exit', (code) => console.log('MCP Process Exited:', code));\r\n    }\r\n\r\n    private handleMessage(line: string) {\r\n        try {\r\n            if (!line.trim()) return;\r\n            const message = JSON.parse(line);\r\n\r\n            // Handle Response\r\n            if (message.id !== undefined && (message.result !== undefined || message.error !== undefined)) {\r\n                const handler = this.pendingRequests.get(message.id);\r\n                if (handler) {\r\n                    this.pendingRequests.delete(message.id);\r\n                    if (message.error) {\r\n                        handler.reject(new Error(message.error.message));\r\n                    } else {\r\n                        handler.resolve(message.result);\r\n                    }\r\n                }\r\n            } else {\r\n                // Handle Notification or Request from server (not implemented deep yet)\r\n                // console.log('Received notification from MCP:', message);\r\n            }\r\n        } catch (e) {\r\n            console.error('Failed to parse MCP message:', line, e);\r\n        }\r\n    }\r\n\r\n    public async sendRequest(method: string, params?: any): Promise<any> {\r\n        const id = this.sequence++;\r\n        const request: JsonRpcRequest = {\r\n            jsonrpc: '2.0',\r\n            method,\r\n            params,\r\n            id,\r\n        };\r\n\r\n        return new Promise((resolve, reject) => {\r\n            this.pendingRequests.set(id, { resolve, reject });\r\n            try {\r\n                if (!this.process.stdin) throw new Error('Stdin not available');\r\n                const data = JSON.stringify(request) + '\\n';\r\n                this.process.stdin.write(data);\r\n            } catch (e) {\r\n                this.pendingRequests.delete(id);\r\n                reject(e);\r\n            }\r\n        });\r\n    }\r\n\r\n    public sendNotification(method: string, params?: any) {\r\n        if (!this.process.stdin) return;\r\n        const notification: JsonRpcRequest = {\r\n            jsonrpc: '2.0',\r\n            method,\r\n            params,\r\n        };\r\n        this.process.stdin.write(JSON.stringify(notification) + '\\n');\r\n    }\r\n\r\n    public disconnect() {\r\n        this.process.kill();\r\n    }\r\n}\r\n"
+    },
+    {
+      "role": "assistant",
+      "content": "\nYes, I have MCP (Model Context Protocol) capability! The system includes a full MCP implementation with:\n\n**MCP Components:**\n- `McpClient.ts` - Main client for communicating with MCP servers\n- `JsonRpcClient.ts` - JSON-RPC communication handler\n- Support for dynamic tool loading from MCP servers\n\n**Key Features:**\n1. **Server Initialization** - Connects to MCP servers using command-line processes\n2. **Tool Discovery** - Automatically lists available tools from connected servers\n3. **Tool Execution** - Calls MCP tools with arguments and returns results\n4. **Error Handling** - Proper error handling and process management\n\n**How it works:**\n- Spawns external MCP server processes\n- Uses JSON-RPC 2.0 protocol for communication\n- Adapts MCP tools to the internal Tool interface\n- Supports text content extraction from tool responses\n\nThe MCP system allows integrating external tools and services seamlessly into the Mentis CLI, extending functionality beyond the built-in tools.\n\nWould you like me to show you how to use it or help you set up an MCP server connection?"
+    }
+  ],
+  "files": []
+}

package/ARCHITECTURE.md

@@ -0,0 +1,267 @@
+# Mentis CLI Architecture
+
+## Overview
+
+Mentis CLI is an agentic, multi-model CLI coding assistant built with TypeScript. It provides an interactive REPL for AI-assisted coding with support for multiple LLM providers (Gemini, Ollama, Anthropic, OpenAI-compatible).
+
+## Project Structure
+
+```
+mentis-cli/
+├── src/
+│   ├── index.ts              # CLI entry point, argument parsing
+│   ├── repl/                 # REPL session management
+│   │   ├── ReplManager.ts    # Main REPL controller
+│   │   └── HistoryManager.ts # Chat history persistence
+│   ├── llm/                  # LLM provider implementations
+│   │   ├── ModelInterface.ts # Shared interfaces
+│   │   ├── Gemini.ts         # Google Gemini provider
+│   │   ├── Ollama.ts         # Ollama local provider
+│   │   ├── Anthropic.ts      # Anthropic Claude provider
+│   │   └── OpenAI.ts         # OpenAI-compatible provider
+│   ├── tools/                # Tool implementations
+│   │   ├── ToolManager.ts    # Tool registry
+│   │   ├── LoadSkillTool.ts  # Agent Skills tool
+│   │   └── ...               # Individual tools
+│   ├── commands/             # Custom Slash Commands
+│   │   ├── Command.ts        # Command interfaces
+│   │   └── CommandManager.ts # Command discovery & parsing
+│   ├── skills/               # Agent Skills system
+│   │   ├── Skill.ts          # Skill interfaces
+│   │   ├── SkillsManager.ts  # Skill discovery & validation
+│   │   └── LoadSkillTool.ts  # Tool for loading skills
+│   ├── ui/                   # User interface
+│   │   ├── UIManager.ts      # Display formatting
+│   │   └── InputBox.ts       # Input prompt with history
+│   ├── mcp/                  # Model Context Protocol
+│   │   └── McpManager.ts     # MCP server management
+│   └── utils/                # Utilities
+│       ├── ContextVisualizer.ts  # Token usage display
+│       ├── UpdateManager.ts     # Auto-update
+│       └── ...
+├── dist/                     # Compiled JavaScript
+├── .mentis/                  # Project-specific config
+└── package.json
+```
+
+## Core Components
+
+### 1. REPL System (`src/repl/`)
+
+The **ReplManager** is the heart of Mentis CLI. It orchestrates the entire conversation flow:
+
+```
+User Input → Command Parser → Skill/Command Handler → LLM → Tool Execution → Response
+```
+
+**Key responsibilities:**
+- Manage chat history with auto-compact at 80% context
+- Handle slash commands (`/help`, `/clear`, `/skills`, etc.)
+- Inject skills and custom commands into system prompt
+- Execute tool calls returned by LLM
+- Save/restore session checkpoints
+
+### 2. LLM Abstraction (`src/llm/`)
+
+Each LLM provider implements the `ModelInterface`:
+
+```typescript
+interface ModelInterface {
+    chat(messages: ChatMessage[], tools?: ToolInfo[]): Promise<ChatResponse>;
+    streamChat(messages: ChatMessage[], tools?: ToolInfo[]): AsyncIterator<ChatChunk>;
+}
+```
+
+**Supported providers:**
+- **Gemini** (Google) - Default, supports streaming
+- **Ollama** - Local models via API
+- **Anthropic** - Claude models
+- **OpenAI-compatible** - Custom endpoints
+
+### 3. Tool System (`src/tools/`)
+
+Tools are functions the AI can invoke. Each tool implements:
+
+```typescript
+interface Tool {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+    execute(params: Record<string, unknown>): Promise<ToolResult>;
+}
+```
+
+**Available tools:**
+- File operations: `Read`, `Write`, `Edit`, `Glob`, `Grep`
+- Execution: `Bash`
+- Git: `GitStatus`, `GitDiff`, `GitCommit`
+- Skills: `LoadSkillTool` (progressive disclosure)
+
+### 4. Agent Skills (`src/skills/`)
+
+Agent Skills are reusable AI configurations stored as `SKILL.md` files:
+
+```
+~/.mentis/skills/
+└── code-reviewer/
+    └── SKILL.md
+```
+
+**Features:**
+- Progressive disclosure (metadata loaded first, content on-demand)
+- Optional tool restrictions
+- Validation (name format, description quality)
+- Personal vs project scopes
+
+### 5. Custom Commands (`src/commands/`)
+
+Custom slash commands defined as markdown files:
+
+```
+~/.mentis/commands/
+└── test.md
+```
+
+**Features:**
+- Parameter substitution (`$1`, `$2`, `$ARGUMENTS`)
+- Bash execution (`!`cmd``)
+- File references (`@file`)
+- Namespace support (subdirectories)
+
+## Data Flow
+
+### Conversation Flow
+
+```
+1. User enters input
+2. Check for slash commands
+3. Inject skills/commands context
+4. Call LLM with tools
+5. Parse tool calls
+6. Execute tools
+7. Return results to LLM
+8. Stream response to user
+9. Update history
+10. Check context usage (compact if >80%)
+```
+
+### Tool Execution Flow
+
+```
+LLM returns tool call
+↓
+ToolManager finds tool
+↓
+Validate parameters
+↓
+Execute tool
+↓
+Format result
+↓
+Return to LLM for final response
+```
+
+### Skill Loading Flow
+
+```
+Startup: Load all skill metadata (name, description)
+↓
+User mentions skill keyword
+↓
+LoadSkillTool invoked
+↓
+Load full SKILL.md content
+↓
+Inject into system prompt
+↓
+AI executes with skill context
+```
+
+## Configuration
+
+### Environment Variables
+
+```bash
+GEMINI_API_KEY=xxx          # Gemini API key
+OLLAMA_BASE_URL=http://...  # Ollama endpoint
+ANTHROPIC_API_KEY=xxx       # Anthropic key
+OPENAI_API_KEY=xxx          # OpenAI-compatible key
+OPENAI_BASE_URL=http://...  # Custom endpoint
+```
+
+### Dotenv Config (`.mentis.md`)
+
+```yaml
+model: gemini-2.5-pro
+temperature: 0.7
+max_tokens: 8192
+```
+
+### Directory Structure
+
+```
+~/.mentis/                   # User config
+├── skills/                  # Personal skills
+├── commands/                # Personal commands
+└── checkpoints/             # Session saves
+
+.mentis/                     # Project config
+├── skills/                  # Project skills
+├── commands/                # Project commands
+└── .mentis.md              # Project config file
+```
+
+## Testing
+
+Jest tests are located in `src/**/__tests__/`:
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```
+
+**Current test coverage:**
+- CommandManager - Command parsing, argument substitution
+- SkillsManager - Skill discovery, validation
+- ContextVisualizer - Token calculation, compacting
+
+## Extension Points
+
+### Adding a New LLM Provider
+
+1. Implement `ModelInterface` in `src/llm/`
+2. Add to `ModelFactory.ts`
+3. Add CLI option for selection
+
+### Adding a New Tool
+
+1. Create tool class in `src/tools/`
+2. Register in `ToolManager.ts`
+3. Update documentation
+
+### Adding a New Slash Command
+
+Create `.md` file in `~/.mentis/commands/`:
+
+```markdown
+---
+description: My custom command
+---
+
+Execute: !`echo "$1"`
+```
+
+## Performance Considerations
+
+- **Streaming**: All LLM calls use streaming for faster perceived response
+- **Progressive Disclosure**: Skills loaded on-demand to reduce startup time
+- **Auto-Compact**: History automatically compacted at 80% context to prevent errors
+- **Caching**: Discovered skills/commands cached in memory
+
+## Security
+
+- API keys stored in environment variables or `.env`
+- No credentials in code or config files
+- Tool execution sandboxed (respects system permissions)
+- Git operations require explicit confirmation (unless `--yolo`)

package/CONTRIBUTING.md

@@ -0,0 +1,209 @@
+# Contributing to Mentis CLI
+
+Thank you for your interest in contributing to Mentis CLI! This document provides guidelines for contributing.
+
+## Table of Contents
+
+- [Development Setup](#development-setup)
+- [Project Structure](#project-structure)
+- [Coding Standards](#coding-standards)
+- [Testing](#testing)
+- [Submitting Changes](#submitting-changes)
+- [Feature Ideas](#feature-ideas)
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm or yarn
+- Git
+
+### Fork and Clone
+
+```bash
+# Fork the repository on GitHub
+git clone https://github.com/YOUR_USERNAME/Mentis-CLI.git
+cd Mentis-CLI
+```
+
+### Install Dependencies
+
+```bash
+npm install
+# or with legacy peer deps if needed
+npm install --legacy-peer-deps
+```
+
+### Build
+
+```bash
+npm run build
+```
+
+### Link for Local Testing
+
+```bash
+npm link
+# Now you can run 'mentis' anywhere
+```
+
+## Project Structure
+
+Key directories:
+
+- `src/` - TypeScript source code
+- `src/llm/` - LLM provider implementations
+- `src/tools/` - Tool implementations
+- `src/skills/` - Agent Skills system
+- `src/commands/` - Custom Commands system
+- `src/ui/` - User interface components
+- `src/**/__tests__/` - Jest test files
+
+## Coding Standards
+
+### TypeScript
+
+- Use strict TypeScript settings
+- Add JSDoc comments for exported functions/classes
+- Define interfaces for all complex types
+
+### Code Style
+
+- Use 4 spaces for indentation
+- Prefer `const` over `let`
+- Use arrow functions for callbacks
+- Add error handling with specific error codes
+
+### Naming Conventions
+
+- Classes: `PascalCase`
+- Functions/variables: `camelCase`
+- Interfaces: `PascalCase` with `I` prefix avoided
+- Private members: `camelCase` with no prefix (TypeScript's `private` keyword)
+
+### Example
+
+```typescript
+/**
+ * Calculate token usage from message history
+ */
+export function calculateUsage(history: ChatMessage[]): ContextUsage {
+    let totalChars = 0;
+
+    for (const msg of history) {
+        if (msg.content) {
+            totalChars += msg.content.length;
+        }
+    }
+
+    return {
+        tokens: Math.ceil(totalChars / 4),
+        percentage: Math.round((totalChars / maxTokens) * 100),
+        maxTokens
+    };
+}
+```
+
+## Testing
+
+### Running Tests
+
+```bash
+npm test              # Run all tests
+npm run test:watch    # Watch mode
+npm run test:coverage # Coverage report
+```
+
+### Writing Tests
+
+- Place test files in `src/**/__tests__/`
+- Name test files: `*.test.ts`
+- Use Jest conventions (`describe`, `it`, `expect`)
+
+### Example Test
+
+```typescript
+describe('MyFunction', () => {
+    it('should return expected result', () => {
+        const result = myFunction('input');
+        expect(result).toBe('expected');
+    });
+});
+```
+
+### Test Coverage
+
+Aim for:
+- Branches: 50%+
+- Functions: 70%+
+- Lines: 70%+
+
+## Submitting Changes
+
+### Commit Messages
+
+Use conventional commit format:
+
+```
+type(scope): description
+
+feat(tools): add new file search tool
+fix(repl): handle empty input gracefully
+docs(readme): update installation instructions
+test(skills): add validation tests
+```
+
+### Pull Request Process
+
+1. Create a branch from `main`
+2. Make your changes
+3. Add/update tests
+4. Run tests: `npm test`
+5. Build: `npm run build`
+6. Commit with conventional message
+7. Push to your fork
+8. Open a pull request
+
+### PR Checklist
+
+- [ ] Tests pass
+- [ ] New features include tests
+- [ ] Documentation updated
+- [ ] Commit messages follow conventions
+- [ ] No console errors/warnings
+
+## Feature Ideas
+
+Looking for something to work on? Here are some ideas:
+
+### High Priority
+
+- [ ] Add more LLM providers (Mistral, Cohere, etc.)
+- [ ] Implement MCP server protocol
+- [ ] Add skill templates/generator
+- [ ] Improve error recovery
+
+### Medium Priority
+
+- [ ] Add conversation search
+- [ ] Implement plugin system
+- [ ] Add code generation templates
+- [ ] Improve completions for custom commands
+
+### Low Priority
+
+- [ ] Add themes for UI
+- [ ] Implement voice input
+- [ ] Add collaborative features
+- [ ] Create web UI
+
+## Questions?
+
+- Open an issue for bugs or feature requests
+- Start a discussion for questions
+- Check existing issues before creating new ones
+
+## License
+
+By contributing, you agree that your contributions will be licensed under the ISC License.

package/README.md

@@ -53,6 +53,23 @@ Type `/model` inside the CLI to launch the interactive configuration wizard:
 
 *Credentials are stored securely in `~/.mentisrc`.*
 
+### Web Search (Optional)
+
+Mentis includes web search capabilities for documentation and error solving. To enable it:
+
+1. **Get a free Tavily API key** at https://tavily.com
+2. Add to your `.env` file in your project directory:
+   ```
+   TAVILY_API_KEY=your_key_here
+   ```
+
+Alternatively, you can use **Exa** via MCP:
+```bash
+export EXA_API_KEY=your_key_here
+mentis
+/mcp connect "Exa Search"
+```
+
 ## 📖 Usage
 
 ### Modes

package/dist/checkpoint/CheckpointManager.js

@@ -49,5 +49,97 @@ class CheckpointManager {
         const filePath = path_1.default.join(this.checkpointDir, `${name}.json`);
         return fs_extra_1.default.existsSync(filePath);
     }
+    // ─── Per-Directory Local Session Methods ───────────────────────────────
+    getLocalSessionsDir(cwd) {
+        return path_1.default.join(cwd, '.mentis', 'sessions');
+    }
+    saveLocalSession(cwd, history, files) {
+        const timestamp = Date.now();
+        const checkpoint = {
+            timestamp,
+            name: `session-${timestamp}`,
+            history,
+            files
+        };
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        fs_extra_1.default.ensureDirSync(sessionsDir);
+        const filePath = path_1.default.join(sessionsDir, `${timestamp}.json`);
+        fs_extra_1.default.writeJsonSync(filePath, checkpoint, { spaces: 2 });
+        return filePath;
+    }
+    loadLocalSession(cwd, sessionId) {
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        if (!fs_extra_1.default.existsSync(sessionsDir))
+            return null;
+        let filePath;
+        if (sessionId) {
+            filePath = path_1.default.join(sessionsDir, `${sessionId}.json`);
+        }
+        else {
+            // Load most recent
+            const sessions = this.listLocalSessions(cwd);
+            if (sessions.length === 0)
+                return null;
+            filePath = path_1.default.join(sessionsDir, `${sessions[0].id}.json`);
+        }
+        if (fs_extra_1.default.existsSync(filePath)) {
+            return fs_extra_1.default.readJsonSync(filePath);
+        }
+        return null;
+    }
+    listLocalSessions(cwd) {
+        const sessionsDir = this.getLocalSessionsDir(cwd);
+        if (!fs_extra_1.default.existsSync(sessionsDir))
+            return [];
+        const files = fs_extra_1.default.readdirSync(sessionsDir);
+        return files
+            .filter(f => f.endsWith('.json'))
+            .map(f => {
+            const filePath = path_1.default.join(sessionsDir, f);
+            try {
+                const data = fs_extra_1.default.readJsonSync(filePath);
+                // Extract meaningful preview from LAST user message (to show current state)
+                const lastUserMsg = [...(data.history || [])].reverse().find(m => m.role === 'user');
+                let preview = 'No preview';
+                if (lastUserMsg?.content) {
+                    let clean = lastUserMsg.content;
+                    // 1. Remove Repository Structure (explicitly)
+                    clean = clean.replace(/Repository Structure:[\s\S]*?(?=\n\n|$)/g, '');
+                    // 2. Remove "User Question:" label (if context insertion logic used it)
+                    clean = clean.replace(/User Question:\s*/g, '');
+                    // 3. Remove "Available Custom Commands" block
+                    clean = clean.replace(/Available Custom Commands:[\s\S]*?(?=\n\n|$)/g, '');
+                    // 4. Remove "Available Skills" block (if present)
+                    clean = clean.replace(/Available Skills \([\s\S]*?(?=\n\n|$)/g, '');
+                    clean = clean.replace(/Available Skills:[\s\S]*?(?=\n\n|$)/g, '');
+                    // 5. Remove [SYSTEM: ...] instructions at the end
+                    clean = clean.replace(/\n\[SYSTEM:[\s\S]*?\]$/g, '');
+                    // 6. Clean up code blocks references/markdown if they were just context
+                    const text = clean.trim();
+                    if (text) {
+                        // Take the first 50 chars of what's left
+                        preview = text.substring(0, 50).replace(/\n/g, ' ');
+                    }
+                    else {
+                        preview = 'New Session';
+                    }
+                }
+                return {
+                    id: f.replace('.json', ''),
+                    timestamp: data.timestamp,
+                    messageCount: data.history?.length || 0,
+                    preview: preview.length >= 50 ? preview + '...' : preview
+                };
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((s) => s !== null)
+            .sort((a, b) => b.timestamp - a.timestamp); // Most recent first
+    }
+    localSessionExists(cwd) {
+        return this.listLocalSessions(cwd).length > 0;
+    }
 }
 exports.CheckpointManager = CheckpointManager;

package/dist/commands/Command.js

@@ -1,6 +1,20 @@
 "use strict";
 /**
  * Custom Slash Commands System
- * Users can define their own slash commands as markdown files
+ *
+ * Users can define their own slash commands as markdown files with YAML frontmatter.
+ * Commands support parameter substitution, bash execution, and file references.
+ *
+ * @packageDocumentation
+ *
+ * @example
+ * ```markdown
+ * ---
+ * description: Run tests and show coverage
+ * argument-hint: [test-pattern]
+ * ---
+ *
+ * Run tests with !`npm test $1`
+ * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });