mentask 0.19.5

MentAsk: Universal AI Coding Agent with multi-provider support via models.dev

mentask

Autonomous AI Coding Agent for the Terminal

---

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
• How it works
• Features
  • Agentic Tool Engine
• Project Isolation (/init)
  • Human-in-the-loop safety
  • Streaming terminal UX
  • Persistent session history
• New in v0.18.5: Lisan al-Gaib
  • 1. Persistent Gem-Style Renderer
  • 2. Intelligence Tools (Working Memory & Planning)
  • 3. Self-Critique & Error Correction
  • 4. Advanced UX Commands
• Installation
  • Prerequisites
  • From Source
  • Via Pip
• Configuration
  • API key (Standardized)
  • Hierarchical Knowledge Hub
• Multimodal Intelligence
• Usage
  • Configuration paths
  • Common Workflows
• Slash commands
• Safety model
• Architecture
  • High-Level System Diagram
  • Layer Breakdown
  • Project Structure
• Development & Simulation
  • Setup
  • Reliable Testing Protocol
  • Tests & Linting
• Internationalization
• Repository Standard
• Contributing
• 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 <id>. 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.

From Source

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

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:

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 <name>	Switch Gemini models mid-conversation (history preserved)
/mode [auto/manual]	Toggle between approving actions or automatic execution
/prompt --theme <name>	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 <id>	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 <key>	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

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

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

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

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 for the operating standard to apply across the other repositories.

---

Contributing

Contributions are welcome! Please see CONTRIBUTING.md for our development workflow and code of conduct.

---

License

Licensed under the MIT License. See LICENSE for details.

Built with precision by julesklord.