{"id":49298197,"url":"https://github.com/julesklord/mentask.py","last_synced_at":"2026-05-10T07:03:13.352Z","repository":{"id":293419393,"uuid":"983974353","full_name":"julesklord/mentask.py","owner":"julesklord","description":"cli_first agent tool written in pure python, works with models.dev, dev, and more (WORK IN PROGRESS)","archived":false,"fork":false,"pushed_at":"2026-04-26T04:38:12.000Z","size":38951,"stargazers_count":0,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T05:32:46.433Z","etag":null,"topics":["chatbot","cli","code","code-generation","dev","gemini-ai","gemini-api","tool"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/julesklord.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-05-15T07:47:08.000Z","updated_at":"2026-04-26T04:38:12.000Z","dependencies_parsed_at":"2025-05-15T08:53:17.956Z","dependency_job_id":null,"html_url":"https://github.com/julesklord/mentask.py","commit_stats":null,"previous_names":["julesklord/pygemai","julesklord/askgem.py","julesklord/mentask.py"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/julesklord/mentask.py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Fmentask.py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Fmentask.py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Fmentask.py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Fmentask.py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/julesklord","download_url":"https://codeload.github.com/julesklord/mentask.py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Fmentask.py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32562118,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-03T06:36:36.687Z","status":"ssl_error","status_checked_at":"2026-05-03T06:36:09.306Z","response_time":103,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chatbot","cli","code","code-generation","dev","gemini-ai","gemini-api","tool"],"created_at":"2026-04-26T05:01:34.329Z","updated_at":"2026-05-10T07:03:13.317Z","avatar_url":"https://github.com/julesklord.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/assets/logo.svg\" width=\"120\" alt=\"mentask logo\"\u003e\n\u003c/p\u003e\n\n\u003ch1 align=\"center\"\u003ementask\u003c/h1\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003cstrong\u003eAutonomous AI Coding Agent for the Terminal\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"https://pypi.org/project/mentask/\"\u003e\u003cimg src=\"https://img.shields.io/pypi/v/mentask.svg\" alt=\"PyPI version\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://www.python.org/downloads/\"\u003e\u003cimg src=\"https://img.shields.io/badge/python-3.10%2B-blue.svg\" alt=\"Python 3.10+\"\u003e\u003c/a\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/License-MIT-blue.svg\" alt=\"License: MIT\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://models.dev/\"\u003e\u003cimg src=\"https://img.shields.io/badge/Powered%20by-models.dev-6366f1\" alt=\"Powered by models.dev\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/astral-sh/ruff\"\u003e\u003cimg src=\"https://img.shields.io/badge/code%20style-ruff-000000.svg\" alt=\"Code style: ruff\"\u003e\u003c/a\u003e\u003cbr\u003e\n  \u003ca href=\"https://github.com/julesklord/mentask.py/actions/workflows/security.yml\"\u003e\u003cimg src=\"https://github.com/julesklord/mentask.py/actions/workflows/security.yml/badge.svg\" alt=\"Security Scan\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/julesklord/mentask.py/actions/workflows/python-ci.yml\"\u003e\u003cimg src=\"https://github.com/julesklord/mentask.py/actions/workflows/python-ci.yml/badge.svg\" alt=\"Python CI (Pro)\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://github.com/julesklord/mentask.py/actions/workflows/release.yml\"\u003e\u003cimg src=\"https://github.com/julesklord/mentask.py/actions/workflows/release.yml/badge.svg\" alt=\"CD - Release\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n---\n\n**WORK IN PROGRESS** | *Professional intelligence for complex codebases*\n\n---\n\n**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.\n\nNo GUI. No cloud sync. No bloat. Just a fast, opinionated CLI agent you can trust with your codebase.\n\n---\n\n## Contents\n\n- [Contents](#contents)\n- [How it works](#how-it-works)\n- [Features](#features)\n  - [Agentic Tool Engine](#agentic-tool-engine)\n- [Project Isolation (/init)](#project-isolation-init)\n  - [Human-in-the-loop safety](#human-in-the-loop-safety)\n  - [Streaming terminal UX](#streaming-terminal-ux)\n  - [Persistent session history](#persistent-session-history)\n- [New in v0.18.5: Lisan al-Gaib](#new-in-v0185-lisan-al-gaib)\n  - [1. Persistent Gem-Style Renderer](#1-persistent-gem-style-renderer)\n  - [2. Intelligence Tools (Working Memory \\\u0026 Planning)](#2-intelligence-tools-working-memory--planning)\n  - [3. Self-Critique \\\u0026 Error Correction](#3-self-critique--error-correction)\n  - [4. Advanced UX Commands](#4-advanced-ux-commands)\n- [Installation](#installation)\n  - [Prerequisites](#prerequisites)\n  - [From Source](#from-source)\n  - [Via Pip](#via-pip)\n- [Configuration](#configuration)\n  - [API key (Standardized)](#api-key-standardized)\n  - [Hierarchical Knowledge Hub](#hierarchical-knowledge-hub)\n- [Multimodal Intelligence](#multimodal-intelligence)\n- [Usage](#usage)\n  - [Configuration paths](#configuration-paths)\n  - [Common Workflows](#common-workflows)\n- [Slash commands](#slash-commands)\n- [Safety model](#safety-model)\n- [Architecture](#architecture)\n  - [High-Level System Diagram](#high-level-system-diagram)\n  - [Layer Breakdown](#layer-breakdown)\n  - [Project Structure](#project-structure)\n- [Development \\\u0026 Simulation](#development--simulation)\n  - [Setup](#setup)\n  - [Reliable Testing Protocol](#reliable-testing-protocol)\n  - [Tests \\\u0026 Linting](#tests--linting)\n- [Internationalization](#internationalization)\n- [Repository Standard](#repository-standard)\n- [Contributing](#contributing)\n- [License](#license)\n\n---\n\n## How it works\n\nmentask runs an advanced asynchronous reasoning loop powered by the **AgentOrchestrator** and a modular manager-based core. On each turn:\n\n1. **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.\n2. **Cognitive Loop**: Your message is processed by the **AgentOrchestrator**, which manages the *Thinking -\u003e Action -\u003e Observation* cycle.\n3. **Tool Reasoning**: The model calls specialized tools (read, edit, execute). mentask intercepts these via the **ToolDispatcher**.\n4. **Safety Guard**: Every action passes through the **Security Layer** for real-time risk analysis and path validation.\n5. **Stream Processing**: The **StreamProcessor** extracts function calls and text mid-flight, showing you the agent's \"thought process\" in real-time.\n6. **Persistence**: The full session, including tool results and metrics, is auto-saved to your Workspace history.\n\nThis autonomous loop repeats until the mission is accomplished or you interrupt it.\n\n---\n\n## Features\n\n### Agentic Tool Engine\n\n| Tool | Description |\n|---|---|\n| `list_directory` | Explore filesystem trees with depth control |\n| `read_file` | Read any file with optional line ranges — 30k char cap prevents token overflow |\n| `edit_file` | Find-and-replace with **atomic writing**, uniqueness guard, and automatic `.bkp` backup |\n| `execute_bash` | Run shell commands with 60s timeout and full **Risk Analysis** |\n| `analyze_codebase` | Perform high-speed repository mapping and git delta analysis |\n| `delegate_mission` | Spawn specialized **Subagents** (Explorer, Verifier) for autonomous research or adversarial testing |\n| `manage_memory` | Save important project facts to `memory.md` for long-term recall |\n| `manage_mission` | Track complex goals and sub-tasks via `heartbeat.md` mission control |\n\n## Project Isolation (/init)\n\nmentask now distinguishes between your **Global Persona** and your **Project Context**:\n\n- **Local Isolation**: Run `/init` to create a dedicated `.mentask/` folder in your project. This isolates sessions, settings, and identity to the current directory.\n- **Local Priority**: If a `.mentask/` folder exists, it takes precedence for settings, memory, and history.\n- **Project Memory**: Knowledge saved via `manage_memory` is stored in `.mentask/memory.md` (or `.mentask_knowledge.md` as fallback), preventing context leakage between repositories.\n- **Project Identity**: Customize mentask's personality for a specific project via `.mentask/identity.md`.\n\n### Human-in-the-loop safety\n\nEvery destructive action is categorized by risk level (`SAFE`, `NOTICE`, `WARNING`, `DANGEROUS`).\nSwitch modes anytime mid-session:\n\n- **`/mode manual`** (default) — approve each file edit and shell command.\n- **`/mode auto`** — trust the agent fully; all actions execute without prompts.\n\n### Streaming terminal UX\n\nmentask now runs through a Rich-based terminal renderer:\n\n- Real-time Markdown streaming in the terminal.\n- Inline confirmations for file edits and shell commands.\n- Focus on a fast, scriptable CLI flow instead of a separate dashboard app.\n\n### Persistent session history\n\nEvery conversation auto-saves to `~/.mentask/history/` as JSON. Reload any past session with `/history load \u003cid\u003e`. A rolling context window and proactive summarization keep reloaded sessions within token budget.\n\n---\n\n---\n\n## New in v0.19.0: Water of Life\n\nThe \"Specialist Collective\" update introduces high-performance agent patterns ported from the `reference_code` standard.\n\n### 1. Autonomous Delegation (`delegate_mission`)\n\nThe main agent can now spawn specialized subagents to offload context-heavy tasks:\n\n- **Explorer**: Read-only specialist for deep repository research.\n- **Verifier**: Adversarial agent that tries to \"break\" implementations before reporting success.\n\n### 2. High-Speed Analysis (`analyze_codebase`)\n\nA \"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.\n\n### 3. Professional Efficiency (Level 403)\n\nUpdated system instructions prioritize \"Measure Twice, Cut Once\" philosophy, forcing agents to analyze first, use surgical reads, and provide verification evidence.\n\n### 4. Persistent Gem-Style Renderer\n\nA 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.\n\n---\n\n## Installation\n\n### Prerequisites\n\n- Python 3.10+\n- A Google API Key — free at [Google AI Studio](https://aistudio.google.dev/).\n\n### From Source\n\n```bash\ngit clone https://github.com/julesklord/mentask\ncd mentask.py\npython -m venv venv\n# On Windows: venv\\Scripts\\activate\nsource venv/bin/activate\npip install -e \".[dev]\"\n```\n\n### Via Pip\n\n```bash\npip install mentask\n```\n\n---\n\n## Configuration\n\n### API key (Standardized)\n\nmentask loads your key from these sources, in order:\n\n1. **Environment variable** — `GEMINI_API_KEY=your_key mentask` (Preferred)\n2. **System Keyring** — Secure storage via Windows Credential Manager or macOS Keychain.\n3. **Saved file** — `~/.mentask/settings.json` (Local fallback).\n\n### Hierarchical Knowledge Hub\n\nThe agent reloads its intelligence every turn from three layers:\n\n1. **Standard Hub (Internal)**: Built-in modules defining the \"Staff Engineer\" persona, operational safety rules, and multimodal guidelines (audio/video/vision).\n2. **Global Hub (`~/.mentask/*.md`)**: Your cross-project technical preferences, API guidelines, or personal style.\n3. **Project Hub (`.mentask/*.md`)**: Project-specific context, build commands, architecture rules, and \"Mission\" specifics.\n\n\u003e [!TIP]\n\u003e Just drop a `.md` file in any of these locations to instantly update mentask's cognitive behavior without touching the code.\n\n---\n\n## Multimodal Intelligence\n\nFully optimized for Gemini 1.5 Pro and 2.0 Flash:\n\n- **Screenshots**: Analyze UI layouts and design systems.\n- **Video**: Summarize technical demos and terminal recordings.\n- **Audio**: Digest project discussions and voice notes.\n\n---\n\n## Usage\n\nLaunch the agent:\n\n```bash\nmentask\n```\n\n### Configuration paths\n\n| Path | Purpose |\n|---|---|\n| `~/.mentask/settings.json` | Model name, edit mode, and user preferences |\n| `~/.mentask/history/` | Auto-saved session JSON files |\n| `~/.mentask/mentask.log` | Debug log — tool execution events and retry details |\n\n### Common Workflows\n\n- **Context Analysis**: \"Read my `pyproject.toml` and explain the dependencies.\"\n- **Code Generation**: \"Create a `src/utils.py` file with a function to calculate SHA256 hashes.\"\n- **Refactoring**: \"Refactor `authenticate()` in `src/auth.py` to use JWT instead of sessions.\"\n\n---\n\n## Slash commands\n\n| Command | Description |\n|---|---|\n| `/help` | Show the full command reference and examples |\n| `/init` | Initialize local project isolation and configuration |\n| `/model \u003cname\u003e` | Switch Gemini models mid-conversation (history preserved) |\n| `/mode [auto/manual]` | Toggle between approving actions or automatic execution |\n| `/prompt --theme \u003cname\u003e` | Customize the interactive prompt style |\n| `/theme [name]` | List or change UI themes |\n| `/stream [mode]` | Change streaming display mode (continuous/transient) |\n| `/clear` | Reset the context window to free up tokens |\n| `/compact` | Compress conversation history to save tokens |\n| `/sessions` | List previous chat sessions |\n| `/load \u003cid\u003e` | Load a specific saved session |\n| `/undo` | Rollback the last file modification |\n| `/trust [path]` | Add a directory to the permanent whitelist |\n| `/untrust` | Remove authorization from current directory |\n| `/auth \u003ckey\u003e` | Securely set the Gemini API Key |\n| `/usage` | Show detailed token consumption and estimated cost |\n| `/stats` | Summary of session accomplishments |\n| `/artifacts` | Browse and expand previous tool results |\n\n---\n\n## Safety model\n\n**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.\n\n**Cross-Drive Protection**: On Windows, the agent is blocked from crossing drive letters unless the target is explicitly trusted.\n\n**Risk Analysis Engine**: Every command is categorized:\n\n- `SAFE`: Informative commands (ls, git status).\n- `NOTICE`: Standard operations.\n- `WARNING`: High-risk patterns (sudo, sensitive file access).\n- `DANGEROUS`: Critical risk (rm -rf, world-writable chmod).\n\n**Atomic Writing**: `edit_file` uses a temporary file + rename strategy to prevent corruption.\n**Automatic Backups**: Every file modification creates a backup at `~/.mentask/backups/`.\n\n---\n\n## Architecture\n\nmentask operates across three tightly decoupled layers enforcing strong logical boundaries.\n\n### High-Level System Diagram\n\n```mermaid\nflowchart TD\n    CLI([\"User execution (mentask)\"]) --\u003e Main(cli/main.py)\n    Main --\u003e Renderer(cli/renderer.py)\n    Renderer \u003c--\u003e Orchestrator(agent/orchestrator.py)\n    \n    subgraph Cognitive_Layer [Cognitive Managers]\n        Orchestrator --\u003e Session[agent/core/session.py]\n        Orchestrator --\u003e Context[agent/core/context.py]\n        Orchestrator --\u003e Stream[agent/core/stream.py]\n    end\n\n    Orchestrator \u003c--\u003e GenAI[Google Gemini API]\n    \n    subgraph Security_Layer [Security \u0026 Trust]\n        GenAI -. function calls .-\u003e Trust[core/trust_manager.py]\n        Trust --\u003e SecurityCheck[core/security.py]\n        SecurityCheck --\u003e Tools(tools/)\n    end\n\n    Tools --\u003e localDisk[(Local Workspace)]\n```\n\n### Layer Breakdown\n\n1. **Presentation Layer (`cli/`)**: Handles CLI startup, interactive prompts, and real-time Markdown rendering.\n2. **Cognitive Layer (`agent/`)**: The \"Brain\". Manages state, context blueprints, and mission tracking.\n3. **Security Layer (`core/`)**: The \"Guard\". Gathers risk analysis and whitelisting logic.\n\n### Project Structure\n\n```text\nmentask.py/\n├── src/mentask/\n│   ├── agent/               # Orchestrator and Cognitive Managers\n│   ├── cli/                 # Startup and Rich streaming renderer\n│   ├── core/                # Safety engine and Path resolution\n│   ├── tools/               # Atomic agentic tools\n│   └── locales/             # i18n JSON data (8 languages)\n├── tests/                   # Unit and integration tests\n├── docs/                    # Technical documentation and assets\n└── pyproject.toml\n```\n\n---\n\n## Development \u0026 Simulation\n\n### Setup\n\n```bash\ngit clone https://github.com/julesklord/mentask\ncd mentask.py\npip install -e \".[dev]\"\n```\n\n### Reliable Testing Protocol\n\nmentask introduces a **Simulation Layer**. You can record agent turns and play them back deterministically:\n\n1. **Record**: Set `SIMULATION_MODE=record` to capture interactions.\n2. **Playback**: Run `pytest tests/integration/test_full_agent_loop.py` to verify the logic against the recorded transcript without hitting the real API.\n\n### Tests \u0026 Linting\n\n```bash\npytest tests/                   # full reliable suite\nruff check src/ tests/ --fix    # auto-fix linting violations\n```\n\n---\n\n## Internationalization\n\n| Code | Language | File |\n|---|---|---|\n| `en` | English (Standard) | `en.json` |\n| `es` | Español | `es.json` |\n| `fr` | Français | `fr.json` |\n| `pt` | Português | `pt.json` |\n| `de` | Deutsch | `de.json` |\n| `it` | Italiano | `it.json` |\n| `ja` | 日本語 | `ja.json` |\n| `zh` | 中文 (简体) | `zh.json` |\n\n---\n\n## Repository Standard\n\n`mentask.py` is now the reference repo for structure, hygiene, and architecture conventions in this workspace.\n\nSee [STANDARD.md](STANDARD.md) for the operating standard to apply across the other repositories.\n\n---\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](docs/CONTRIBUTING.md) for our development workflow and code of conduct.\n\n---\n\n## License\n\nLicensed under the **MIT License**. See [LICENSE](LICENSE) for details.\n\nBuilt with precision by [julesklord](https://github.com/julesklord).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesklord%2Fmentask.py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulesklord%2Fmentask.py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesklord%2Fmentask.py/lists"}