Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/julesklord/mentask.py

cli_first agent tool written in pure python, works with models.dev, dev, and more (WORK IN PROGRESS)
https://github.com/julesklord/mentask.py

chatbot cli code code-generation dev gemini-ai gemini-api tool

Last synced: about 1 month ago
JSON representation

cli_first agent tool written in pure python, works with models.dev, dev, and more (WORK IN PROGRESS)

Awesome Lists containing this project

README 

          


  mentask logo




mentask





  Autonomous AI Coding Agent for the Terminal






  PyPI version

  Python 3.10+

  License: MIT

  Powered by models.dev

  Code style: ruff


  Security Scan

  Python CI (Pro)

  CD - Release




---



**WORK IN PROGRESS** | *Professional intelligence for complex codebases*



---



**mentask** is a professional, autonomous coding agent that lives in your terminal. Powered by Google Gemini and a custom orchestration engine, it reads your files, edits your code, runs shell commands, and navigates your filesystem — all within an interactive session and with hardened safety guardrails that keep you in control.



No GUI. No cloud sync. No bloat. Just a fast, opinionated CLI agent you can trust with your codebase.



---



## Contents



- [Contents](#contents)

- [How it works](#how-it-works)

- [Features](#features)

  - [Agentic Tool Engine](#agentic-tool-engine)

- [Project Isolation (/init)](#project-isolation-init)

  - [Human-in-the-loop safety](#human-in-the-loop-safety)

  - [Streaming terminal UX](#streaming-terminal-ux)

  - [Persistent session history](#persistent-session-history)

- [New in v0.18.5: Lisan al-Gaib](#new-in-v0185-lisan-al-gaib)

  - [1. Persistent Gem-Style Renderer](#1-persistent-gem-style-renderer)

  - [2. Intelligence Tools (Working Memory \& Planning)](#2-intelligence-tools-working-memory--planning)

  - [3. Self-Critique \& Error Correction](#3-self-critique--error-correction)

  - [4. Advanced UX Commands](#4-advanced-ux-commands)

- [Installation](#installation)

  - [Prerequisites](#prerequisites)

  - [From Source](#from-source)

  - [Via Pip](#via-pip)

- [Configuration](#configuration)

  - [API key (Standardized)](#api-key-standardized)

  - [Hierarchical Knowledge Hub](#hierarchical-knowledge-hub)

- [Multimodal Intelligence](#multimodal-intelligence)

- [Usage](#usage)

  - [Configuration paths](#configuration-paths)

  - [Common Workflows](#common-workflows)

- [Slash commands](#slash-commands)

- [Safety model](#safety-model)

- [Architecture](#architecture)

  - [High-Level System Diagram](#high-level-system-diagram)

  - [Layer Breakdown](#layer-breakdown)

  - [Project Structure](#project-structure)

- [Development \& Simulation](#development--simulation)

  - [Setup](#setup)

  - [Reliable Testing Protocol](#reliable-testing-protocol)

  - [Tests \& Linting](#tests--linting)

- [Internationalization](#internationalization)

- [Repository Standard](#repository-standard)

- [Contributing](#contributing)

- [License](#license)



---



## How it works



mentask runs an advanced asynchronous reasoning loop powered by the **AgentOrchestrator** and a modular manager-based core. On each turn:



1. **Environmental Awareness**: At startup, the **ContextManager** performs a **Project Blueprint** scan, discovering the project type, structure, and key files to build a proactive system instruction.

2. **Cognitive Loop**: Your message is processed by the **AgentOrchestrator**, which manages the *Thinking -> Action -> Observation* cycle.

3. **Tool Reasoning**: The model calls specialized tools (read, edit, execute). mentask intercepts these via the **ToolDispatcher**.

4. **Safety Guard**: Every action passes through the **Security Layer** for real-time risk analysis and path validation.

5. **Stream Processing**: The **StreamProcessor** extracts function calls and text mid-flight, showing you the agent's "thought process" in real-time.

6. **Persistence**: The full session, including tool results and metrics, is auto-saved to your Workspace history.



This autonomous loop repeats until the mission is accomplished or you interrupt it.



---



## Features



### Agentic Tool Engine



| Tool | Description |

|---|---|

| `list_directory` | Explore filesystem trees with depth control |

| `read_file` | Read any file with optional line ranges — 30k char cap prevents token overflow |

| `edit_file` | Find-and-replace with **atomic writing**, uniqueness guard, and automatic `.bkp` backup |

| `execute_bash` | Run shell commands with 60s timeout and full **Risk Analysis** |

| `analyze_codebase` | Perform high-speed repository mapping and git delta analysis |

| `delegate_mission` | Spawn specialized **Subagents** (Explorer, Verifier) for autonomous research or adversarial testing |

| `manage_memory` | Save important project facts to `memory.md` for long-term recall |

| `manage_mission` | Track complex goals and sub-tasks via `heartbeat.md` mission control |



## Project Isolation (/init)



mentask now distinguishes between your **Global Persona** and your **Project Context**:



- **Local Isolation**: Run `/init` to create a dedicated `.mentask/` folder in your project. This isolates sessions, settings, and identity to the current directory.

- **Local Priority**: If a `.mentask/` folder exists, it takes precedence for settings, memory, and history.

- **Project Memory**: Knowledge saved via `manage_memory` is stored in `.mentask/memory.md` (or `.mentask_knowledge.md` as fallback), preventing context leakage between repositories.

- **Project Identity**: Customize mentask's personality for a specific project via `.mentask/identity.md`.



### Human-in-the-loop safety



Every destructive action is categorized by risk level (`SAFE`, `NOTICE`, `WARNING`, `DANGEROUS`).

Switch modes anytime mid-session:



- **`/mode manual`** (default) — approve each file edit and shell command.

- **`/mode auto`** — trust the agent fully; all actions execute without prompts.



### Streaming terminal UX



mentask now runs through a Rich-based terminal renderer:



- Real-time Markdown streaming in the terminal.

- Inline confirmations for file edits and shell commands.

- Focus on a fast, scriptable CLI flow instead of a separate dashboard app.



### Persistent session history



Every conversation auto-saves to `~/.mentask/history/` as JSON. Reload any past session with `/history load `. A rolling context window and proactive summarization keep reloaded sessions within token budget.



---



---



## New in v0.19.0: Water of Life



The "Specialist Collective" update introduces high-performance agent patterns ported from the `reference_code` standard.



### 1. Autonomous Delegation (`delegate_mission`)



The main agent can now spawn specialized subagents to offload context-heavy tasks:



- **Explorer**: Read-only specialist for deep repository research.

- **Verifier**: Adversarial agent that tries to "break" implementations before reporting success.



### 2. High-Speed Analysis (`analyze_codebase`)



A "first-strike" tool that builds a recursive tree map and analyzes git deltas in milliseconds, ensuring the agent understands the project structure before spending tokens on large reads.



### 3. Professional Efficiency (Level 403)



Updated system instructions prioritize "Measure Twice, Cut Once" philosophy, forcing agents to analyze first, use surgical reads, and provide verification evidence.



### 4. Persistent Gem-Style Renderer



A complete architectural overhaul of the CLI output. All thoughts, tool calls, and results now persist in your terminal scroll buffer, providing a seamless and professional experience.



---



## Installation



### Prerequisites



- Python 3.10+

- A Google API Key — free at [Google AI Studio](https://aistudio.google.dev/).



### From Source



```bash

git clone https://github.com/julesklord/mentask

cd mentask.py

python -m venv venv

# On Windows: venv\Scripts\activate

source venv/bin/activate

pip install -e ".[dev]"

```



### Via Pip



```bash

pip install mentask

```



---



## Configuration



### API key (Standardized)



mentask loads your key from these sources, in order:



1. **Environment variable** — `GEMINI_API_KEY=your_key mentask` (Preferred)

2. **System Keyring** — Secure storage via Windows Credential Manager or macOS Keychain.

3. **Saved file** — `~/.mentask/settings.json` (Local fallback).



### Hierarchical Knowledge Hub



The agent reloads its intelligence every turn from three layers:



1. **Standard Hub (Internal)**: Built-in modules defining the "Staff Engineer" persona, operational safety rules, and multimodal guidelines (audio/video/vision).

2. **Global Hub (`~/.mentask/*.md`)**: Your cross-project technical preferences, API guidelines, or personal style.

3. **Project Hub (`.mentask/*.md`)**: Project-specific context, build commands, architecture rules, and "Mission" specifics.



> [!TIP]

> Just drop a `.md` file in any of these locations to instantly update mentask's cognitive behavior without touching the code.



---



## Multimodal Intelligence



Fully optimized for Gemini 1.5 Pro and 2.0 Flash:



- **Screenshots**: Analyze UI layouts and design systems.

- **Video**: Summarize technical demos and terminal recordings.

- **Audio**: Digest project discussions and voice notes.



---



## Usage



Launch the agent:



```bash

mentask

```



### Configuration paths



| Path | Purpose |

|---|---|

| `~/.mentask/settings.json` | Model name, edit mode, and user preferences |

| `~/.mentask/history/` | Auto-saved session JSON files |

| `~/.mentask/mentask.log` | Debug log — tool execution events and retry details |



### Common Workflows



- **Context Analysis**: "Read my `pyproject.toml` and explain the dependencies."

- **Code Generation**: "Create a `src/utils.py` file with a function to calculate SHA256 hashes."

- **Refactoring**: "Refactor `authenticate()` in `src/auth.py` to use JWT instead of sessions."



---



## Slash commands



| Command | Description |

|---|---|

| `/help` | Show the full command reference and examples |

| `/init` | Initialize local project isolation and configuration |

| `/model ` | Switch Gemini models mid-conversation (history preserved) |

| `/mode [auto/manual]` | Toggle between approving actions or automatic execution |

| `/prompt --theme ` | Customize the interactive prompt style |

| `/theme [name]` | List or change UI themes |

| `/stream [mode]` | Change streaming display mode (continuous/transient) |

| `/clear` | Reset the context window to free up tokens |

| `/compact` | Compress conversation history to save tokens |

| `/sessions` | List previous chat sessions |

| `/load ` | Load a specific saved session |

| `/undo` | Rollback the last file modification |

| `/trust [path]` | Add a directory to the permanent whitelist |

| `/untrust` | Remove authorization from current directory |

| `/auth ` | Securely set the Gemini API Key |

| `/usage` | Show detailed token consumption and estimated cost |

| `/stats` | Summary of session accomplishments |

| `/artifacts` | Browse and expand previous tool results |



---



## Safety model



**Trust Management Layer**: mentask implements a strict whitelist for file operations. By default, it can only touch the current workspace. Use `/trust` to authorize external paths.



**Cross-Drive Protection**: On Windows, the agent is blocked from crossing drive letters unless the target is explicitly trusted.



**Risk Analysis Engine**: Every command is categorized:



- `SAFE`: Informative commands (ls, git status).

- `NOTICE`: Standard operations.

- `WARNING`: High-risk patterns (sudo, sensitive file access).

- `DANGEROUS`: Critical risk (rm -rf, world-writable chmod).



**Atomic Writing**: `edit_file` uses a temporary file + rename strategy to prevent corruption.

**Automatic Backups**: Every file modification creates a backup at `~/.mentask/backups/`.



---



## Architecture



mentask operates across three tightly decoupled layers enforcing strong logical boundaries.



### High-Level System Diagram



```mermaid

flowchart TD

    CLI(["User execution (mentask)"]) --> Main(cli/main.py)

    Main --> Renderer(cli/renderer.py)

    Renderer <--> Orchestrator(agent/orchestrator.py)

    

    subgraph Cognitive_Layer [Cognitive Managers]

        Orchestrator --> Session[agent/core/session.py]

        Orchestrator --> Context[agent/core/context.py]

        Orchestrator --> Stream[agent/core/stream.py]

    end



    Orchestrator <--> GenAI[Google Gemini API]

    

    subgraph Security_Layer [Security & Trust]

        GenAI -. function calls .-> Trust[core/trust_manager.py]

        Trust --> SecurityCheck[core/security.py]

        SecurityCheck --> Tools(tools/)

    end



    Tools --> localDisk[(Local Workspace)]

```



### Layer Breakdown



1. **Presentation Layer (`cli/`)**: Handles CLI startup, interactive prompts, and real-time Markdown rendering.

2. **Cognitive Layer (`agent/`)**: The "Brain". Manages state, context blueprints, and mission tracking.

3. **Security Layer (`core/`)**: The "Guard". Gathers risk analysis and whitelisting logic.



### Project Structure



```text

mentask.py/

├── src/mentask/

│   ├── agent/               # Orchestrator and Cognitive Managers

│   ├── cli/                 # Startup and Rich streaming renderer

│   ├── core/                # Safety engine and Path resolution

│   ├── tools/               # Atomic agentic tools

│   └── locales/             # i18n JSON data (8 languages)

├── tests/                   # Unit and integration tests

├── docs/                    # Technical documentation and assets

└── pyproject.toml

```



---



## Development & Simulation



### Setup



```bash

git clone https://github.com/julesklord/mentask

cd mentask.py

pip install -e ".[dev]"

```



### Reliable Testing Protocol



mentask introduces a **Simulation Layer**. You can record agent turns and play them back deterministically:



1. **Record**: Set `SIMULATION_MODE=record` to capture interactions.

2. **Playback**: Run `pytest tests/integration/test_full_agent_loop.py` to verify the logic against the recorded transcript without hitting the real API.



### Tests & Linting



```bash

pytest tests/                   # full reliable suite

ruff check src/ tests/ --fix    # auto-fix linting violations

```



---



## Internationalization



| Code | Language | File |

|---|---|---|

| `en` | English (Standard) | `en.json` |

| `es` | Español | `es.json` |

| `fr` | Français | `fr.json` |

| `pt` | Português | `pt.json` |

| `de` | Deutsch | `de.json` |

| `it` | Italiano | `it.json` |

| `ja` | 日本語 | `ja.json` |

| `zh` | 中文 (简体) | `zh.json` |



---



## Repository Standard



`mentask.py` is now the reference repo for structure, hygiene, and architecture conventions in this workspace.



See [STANDARD.md](STANDARD.md) for the operating standard to apply across the other repositories.



---



## Contributing



Contributions are welcome! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for our development workflow and code of conduct.



---



## License



Licensed under the **MIT License**. See [LICENSE](LICENSE) for details.



Built with precision by [julesklord](https://github.com/julesklord).