{"id":48765699,"url":"https://github.com/julesklord/askgem.py","last_synced_at":"2026-04-20T09:03:58.064Z","repository":{"id":293419393,"uuid":"983974353","full_name":"julesklord/askgem.py","owner":"julesklord","description":"Agente multimodal para gemini_cli","archived":false,"fork":false,"pushed_at":"2026-04-13T06:23:47.000Z","size":37361,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-04-13T07:51:56.501Z","etag":null,"topics":["chatbot","cli","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":"gpl-3.0","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-12T12:07:50.000Z","dependencies_parsed_at":"2025-05-15T08:53:17.956Z","dependency_job_id":null,"html_url":"https://github.com/julesklord/askgem.py","commit_stats":null,"previous_names":["julesklord/pygemai","julesklord/askgem.py"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/julesklord/askgem.py","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Faskgem.py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Faskgem.py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Faskgem.py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Faskgem.py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/julesklord","download_url":"https://codeload.github.com/julesklord/askgem.py/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/julesklord%2Faskgem.py/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32040358,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-20T00:18:06.643Z","status":"online","status_checked_at":"2026-04-20T02:00:06.527Z","response_time":94,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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","gemini-ai","gemini-api","tool"],"created_at":"2026-04-13T07:50:25.498Z","updated_at":"2026-04-20T09:03:58.057Z","avatar_url":"https://github.com/julesklord.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# askgem — Autonomous AI Coding Agent for the Terminal\r\n\r\n[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/) [![License: GPL v3](https://img.shields.io/badge/License-GPLv3-green.svg)](LICENSE) [![Powered by Gemini](https://img.shields.io/badge/Powered%20by-Google%20Gemini-4285F4?logo=google\u0026logoColor=white)](https://ai.google.dev/) [![Code style: ruff](https://img.shields.io/badge/code%20style-ruff-000000.svg)](https://github.com/astral-sh/ruff) [![Security Scan](https://github.com/julesklord/askgem.py/actions/workflows/security.yml/badge.svg)](https://github.com/julesklord/askgem.py/actions/workflows/security.yml) [![CD - Release](https://github.com/julesklord/askgem.py/actions/workflows/release.yml/badge.svg)](https://github.com/julesklord/askgem.py/actions/workflows/release.yml)\r\n---\r\n\r\n![askgem banner](docs/assets/banner.png)\r\n\r\n---\r\n\r\n**WORK IN PROGRESS**\r\n\r\n---\r\n\r\n**askgem** is a professional, autonomous coding agent that lives in your terminal.\r\nPowered by Google Gemini, it reads your files, edits your code, runs shell commands,\r\nand navigates your filesystem — all within an interactive session and with\r\nhardened safety guardrails that keep you in control.\r\n\r\nNo GUI. No cloud sync. No bloat. Just a fast, opinionated CLI agent you can trust\r\nwith your codebase.\r\n\r\n---\r\n\r\n## Contents\r\n\r\n- [How it works](#how-it-works)\r\n- [Features](#features)\r\n- [New in v0.16.x: The Golden Path](#new-in-v016x-the-golden-path)\r\n- [Project Isolation (/init)](#project-isolation-init)\r\n- [Installation](#installation)\r\n- [Configuration](#configuration)\r\n- [Usage](#usage)\r\n- [Slash commands](#slash-commands)\r\n- [Safety model](#safety-model)\r\n- [Architecture](#architecture)\r\n- [Development \u0026 Simulation](#development--simulation)\r\n- [Internationalization](#internationalization)\r\n- [Repository Standard](#repository-standard)\r\n- [Roadmap](#roadmap)\r\n- [Contributing](#contributing)\r\n- [License](#license)\r\n\r\n---\r\n\r\n## How it works\r\n\r\naskgem runs an advanced asynchronous reasoning loop powered by the **AgentOrchestrator** and a modular manager-based core. On each turn:\r\n\r\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.\r\n2. **Cognitive Loop**: Your message is processed by the **AgentOrchestrator**, which manages the *Thinking -\u003e Action -\u003e Observation* cycle.\r\n3. **Tool Reasoning**: The model calls specialized tools (read, edit, execute). askgem intercepts these via the **ToolDispatcher**.\r\n4. **Safety Guard**: Every action passes through the **Security Layer** for real-time risk analysis and path validation.\r\n5. **Stream Processing**: The **StreamProcessor** extracts function calls and text mid-flight, showing you the agent's \"thought process\" in real-time.\r\n6. **Persistence**: The full session, including tool results and metrics, is auto-saved to your Workspace history.\r\n\r\nThis autonomous loop repeats until the mission is accomplished or you interrupt it.\r\n\r\n---\r\n\r\n## Features\r\n\r\n### Agentic tool engine\r\n\r\n| Tool | Description |\r\n|---|---|\r\n| `list_directory` | Explore filesystem trees with depth control |\r\n| `read_file` | Read any file with optional line ranges — 30k char cap prevents token overflow |\r\n| `edit_file` | Find-and-replace with **atomic writing**, uniqueness guard, and automatic `.bkp` backup |\r\n| `execute_bash` | Run shell commands with 60s timeout and full **Risk Analysis** |\r\n| `manage_memory` | Save important project facts to `memory.md` for long-term recall |\r\n| `manage_mission` | Track complex goals and sub-tasks via `heartbeat.md` mission control |\r\n| `manage_workspace` | Detects and initializes local project knowledge bases |\r\n\r\n### Workspace Isolation \u0026 Local Intelligence\r\n\r\nAskGem now distinguishes between your **Global Persona** and your **Project Context**:\r\n\r\n- **Local Isolation**: Run `/init` to create a dedicated `.askgem/` folder in your project. This isolates sessions, settings, and identity to the current directory.\r\n- **Local Priority**: If a `.askgem/` folder exists, it takes precedence for settings, memory, and history.\r\n- **Project Memory**: Knowledge saved via `manage_memory` is stored in `.askgem/memory.md` (or `.askgem_knowledge.md` as fallback), preventing context leakage between repositories.\r\n- **Project Identity**: Customize AskGem's personality for a specific project via `.askgem/identity.md`.\r\n\r\n### Human-in-the-loop safety\r\n\r\nEvery destructive action is categorized by risk level (`SAFE`, `NOTICE`, `WARNING`, `DANGEROUS`).\r\nSwitch modes anytime mid-session:\r\n\r\n- **`/mode manual`** (default) — approve each file edit and shell command.\r\n- **`/mode auto`** — trust the agent fully; all actions execute without prompts.\r\n\r\n### Streaming terminal UX\r\n\r\nAskGem now runs through a Rich-based terminal renderer:\r\n\r\n- Real-time Markdown streaming in the terminal.\r\n- Inline confirmations for file edits and shell commands.\r\n- Focus on a fast, scriptable CLI flow instead of a separate dashboard app.\r\n\r\n### Persistent session history\r\n\r\nEvery conversation auto-saves to `~/.askgem/history/` as JSON. Reload any past\r\nsession with `/history load \u003cid\u003e`. A rolling context window and proactive summarization\r\nkeep reloaded sessions within token budget.\r\n\r\n---\r\n\r\n## New in v0.16.x: The Golden Path\r\n\r\nThe v0.16.x release cycle (\"The Golden Path\") consolidates the \"Bene Gesserit\" initiative, introducing a professional-grade TUI, real-time autonomous linting, and a highly optimized **On-Demand Knowledge Hub**.\r\n\r\n### 1. Professional TUI Renderer\r\nA sophisticated CLI rendering engine with support for dynamic visual identities (\"Smuffle\" and \"Snuggles\") and high-fidelity Markdown streaming.\r\n\r\n### 2. Autonomous LSP Integration\r\nNative integration with the Ruff Language Server Protocol (LSP) allowing the AgentOrchestrator to verify syntax and fix diagnostics in real-time.\r\n\r\n### 3. On-Demand Knowledge Hub\r\nRefactored the Knowledge Hub from full-text injection to an on-demand retrieval system via the `query_knowledge` tool. This significantly reduces token consumption while maintaining deep context awareness.\r\n\r\n### 4. Project Isolation (/init)\r\nIntroduced in v0.16.4, the `/init` command allows you to isolate AskGem to a specific directory. It creates a `.askgem/` folder containing local settings, a dedicated `sessions/` storage, and an `identity.md` file for project-specific instructions.\r\n\r\n---\r\n\r\n## Installation\r\n\r\n### Prerequisites\r\n\r\n- **Python 3.10+**.\r\n- A **Google API Key** — free at [Google AI Studio](https://aistudio.google.dev/).\r\n\r\n### From source (recommended)\r\n\r\n```bash\r\ngit clone https://github.com/julesklord/askgem.py\r\ncd askgem.py\r\npython -m venv venv\r\n# On Windows: venv\\Scripts\\activate\r\nsource venv/bin/activate\r\npip install -e \".[dev]\"\r\n```\r\n\r\n---\r\n\r\n## Configuration\r\n\r\n### API key (Standardized)\r\n\r\naskgem loads your key from these sources, in order:\r\n\r\n1. **Environment variable** — `GEMINI_API_KEY=your_key askgem` (Preferred)\r\n2. **System Keyring** — Secure storage via Windows Credential Manager or macOS Keychain (Recommended).\r\n3. **Saved file** — `~/.askgem/settings.json` (Local fallback).\r\n\r\nOn first launch without a key, askgem prompts interactively and saves it securely in your system's keyring.\r\n\r\n### Settings file\r\n\r\nYou can find the global configuration at `~/.askgem/settings.json`.\r\n\r\n---\r\n\r\n## 🧠 Core Knowledge Hub\r\n\r\nAskGem now features a **Hierarchical Knowledge Hub**, separating core behavioral rules from user-specific customizations. The agent reloads its intelligence every turn from three layers:\r\n\r\n1.  **📦 Standard Hub (Internal)**: Built-in modules defining the \"Staff Engineer\" persona, operational safety rules, and multimodal guidelines (audio/video/vision).\r\n2.  **🌍 Global Hub (`~/.askgem/*.md`)**: Your cross-project technical preferences, API guidelines, or personal style.\r\n3.  **🚀 Project Hub (`.askgem/*.md`)**: Project-specific context, build commands, architecture rules, and \"Mission\" specifics.\r\n\r\n\u003e [!TIP]\r\n\u003e Just drop a `.md` file in any of these locations to instantly update AskGem's cognitive behavior without touching the code.\r\n\r\n## 👁️ Multimodal Intelligence\r\nFully optimized for Gemini 1.5 Pro and 2.0 Flash:\r\n- **Screenshots**: Analyze UI layouts and design systems.\r\n- **Video**: Summarize technical demos and terminal recordings.\r\n- **Audio**: Digest project discussions and voice notes.\r\n\r\n---\r\n\r\n## Usage\r\n\r\nStored at `~/.askgem/settings.json` (POSIX) or `%APPDATA%\\askgem\\settings.json` (Windows):\r\n\r\n```json\r\n{\r\n    \"model_name\": \"gemini-1.5-flash\",\r\n    \"edit_mode\": \"manual\"\r\n}\r\n```\r\n\r\n### Configuration paths\r\n\r\n| Path | Purpose |\r\n|---|---|\r\n| `~/.askgem/settings.json` | Model name, edit mode, and user preferences |\r\n| `~/.askgem/history/` | Auto-saved session JSON files |\r\n| `~/.askgem/askgem.log` | Debug log — tool execution events and retry details |\r\n\r\n---\r\n\r\n## Usage\r\n\r\nLaunch the agent:\r\n\r\n```bash\r\naskgem\r\n```\r\n\r\n### Common Workflows\r\n\r\n- **Context Analysis:** \"Read my `pyproject.toml` and explain the dependencies.\"\r\n- **Code Generation:** \"Create a `src/utils.py` file with a function to calculate SHA256 hashes.\"\r\n- **Refactoring:** \"Refactor `authenticate()` in `src/auth.py` to use JWT instead of sessions.\"\r\n- **Exploration:** \"Find all TODO comments in the project and group them by file.\"\r\n\r\n### Exiting\r\n\r\nType `exit`, `quit`, `q`, or press `Ctrl+C`.\r\n\r\n---\r\n\r\n## Slash commands\r\n\r\n| Command | Description |\r\n|---|---|\r\n| `/help` | Show the full command reference and examples |\r\n| `/model \u003cname\u003e` | Switch Gemini models mid-conversation (history preserved) |\r\n| `/mode [auto/manual]` | Toggle between approving actions or automatic execution |\r\n| `/clear` | Reset the context window to free up tokens without ending session |\r\n| `/usage` | Show detailed token consumption and estimated USD cost |\r\n| `/stats` | Summary of session accomplishments (messages, tools, files) |\r\n| `/stop` | Interrupt the current generation immediately |\r\n| `/reset` | Restart the entire session and reset all counters |\r\n| `/init` | Initialize local project isolation and configuration |\r\n| `/history [list/load/delete]` | Manage saved conversation sessions |\r\n| `/trust [path]` | Add a directory to the permanent whitelist |\r\n| `/untrust [path]` | Remove a directory from the whitelist |\r\n\r\n---\r\n\r\n## Safety model\r\n\r\n**Always, regardless of mode (Sandboxed Environment):**\r\n\r\n- **Trust Management Layer:** askgem now implements a strict whitelist for file operations. By default, it can only touch the current workspace. Use `/trust` to authorize external paths.\r\n- **Cross-Drive Protection:** On Windows, the agent is blocked from crossing drive letters (e.g., C: to G:) unless the target is explicitly trusted, preventing unintended system-wide access.\r\n- **Risk Analysis Engine:** Powered by `core/security.py`, every command is categorized:\r\n  - `SAFE`: Informative commands (ls, git status).\r\n  - `NOTICE`: Standard operations.\r\n  - `WARNING`: High-risk patterns (sudo, sensitive file access).\r\n  - `DANGEROUS`: Critical risk (rm -rf, fork bombs, world-writable chmod).\r\n- **Atomic Writing:** `edit_file` uses a temporary file + rename strategy to prevent corruption.\r\n- **Automatic Backups:** Every file modification creates a `.bkp` backup at `\u003cpath\u003e.bkp`.\r\n- **Hard Timeouts:** Shell commands have a strict 60-second execution limit.\r\n\r\n---\r\n\r\n## Architecture\r\n\r\nAskGem operates across three tightly decoupled layers enforcing strong logical boundaries. As of version **0.16.0**, the system has evolved into an **Orchestrated Architecture**, where a central engine manages cognitive managers, security centinels, and an autonomous LSP verification loop.\r\n\r\n### High-Level System Diagram\r\n\r\n```mermaid\r\nflowchart TD\r\n    CLI([\"User execution (askgem)\"]) --\u003e Main(cli/main.py)\r\n    Main --\u003e Renderer(cli/renderer.py)\r\n    Renderer \u003c--\u003e Orchestrator(agent/orchestrator.py: AgentOrchestrator)\r\n    \r\n    subgraph Cognitive_Layer [Cognitive Managers]\r\n        Orchestrator --\u003e Session[agent/core/session.py]\r\n        Orchestrator --\u003e Context[agent/core/context.py]\r\n        Orchestrator --\u003e Stream[agent/core/stream.py]\r\n        Orchestrator --\u003e Commands[agent/core/commands.py]\r\n        Orchestrator --\u003e Simulation[agent/core/simulation.py]\r\n    end\r\n\r\n    Orchestrator \u003c--\u003e GenAI[Google Gemini API]\r\n    \r\n    subgraph Security_Layer [Security \u0026 Trust Centinel]\r\n        GenAI -. function calls .-\u003e Trust[core/trust_manager.py]\r\n        Trust --\u003e SecurityCheck[core/security.py]\r\n        SecurityCheck --\u003e Tools(tools/)\r\n    end\r\n\r\n    Tools --\u003e localDisk[(Local Workspace)]\r\n    Context -. Blueprint .-\u003e localDisk\r\n```\r\n\r\n### Layer Breakdown\r\n\r\n1. **Presentation Layer (`cli/`)**: Handles CLI startup, interactive prompts, audit views, and real-time Markdown rendering.\r\n2. **Cognitive Layer (`agent/`)**: The \"Brain\". Powered by the `AgentOrchestrator`, it manages state, context blueprints, and mission tracking.\r\n3. **Security Layer (`core/`)**: The \"Guard\". Gathers risk analysis and whitelisting logic to ensure the agent never exceeds its authority.\r\n\r\n### Project Structure (v0.16.4)\r\n\r\n```\r\naskgem.py/\r\n├── src/askgem/\r\n│   ├── __init__.py              # Single source of truth for version (0.16.4)\r\n│   ├── agent/\r\n│   │   ├── orchestrator.py      # The Reasoning Brain — Thinking/Action/Observation\r\n│   │   ├── schema.py            # Unified message and tool schemas\r\n│   │   └── core/                # Cognitive Managers\r\n│   │       ├── session.py       # API lifecycle, Retries and Error handling\r\n│   │       ├── context.py       # Blueprint, Memory and Mission management\r\n│   │       ├── commands.py      # Slash command handler\r\n│   │       └── simulation.py    # Deterministic loop recording\r\n│   ├── cli/\r\n│   │   ├── main.py              # Entry point and session initialization\r\n│   │   ├── renderer.py          # Rich streaming renderer and interactive prompts\r\n│   ├── core/\r\n│   │   ├── security.py          # Hardened safety engine\r\n│   │   ├── trust_manager.py     # Directory trust whitelist control\r\n│   │   ├── paths.py             # OS-agnostic path resolution (Workspace aware)\r\n│   ├── tools/                   # Atomic agentic tools\r\n│   └── locales/                 # i18n JSON data (8 languages supported)\r\n├── tests/                       # Reliable unit and integration tests\r\n├── scripts/                     # Maintenance and diagnostic utilities\r\n├── docs/                        # Rich documentation and assets\r\n└── pyproject.toml\r\n```\r\n\r\n---\r\n\r\n## Development \u0026 Simulation\r\n\r\n### Setup\r\n\r\n```bash\r\ngit clone https://github.com/julesklord/askgem.py\r\ncd askgem.py\r\npip install -e \".[dev]\"\r\n```\r\n\r\n### Reliable Testing Protocol\r\n\r\nAskGem introduces a **Simulation Layer**. You can record agent turns and play them back deterministically:\r\n\r\n1. **Record:** Set `SIMULATION_MODE=record` to capture interactions.\r\n2. **Playback:** Run `pytest tests/integration/test_full_agent_loop.py` to verify the logic against the recorded transcript without hitting the real API.\r\n\r\n### Tests \u0026 Linting\r\n\r\n```bash\r\npytest tests/                   # full reliable suite\r\nruff check src/ tests/ --fix    # auto-fix linting violations\r\n```\r\n\r\n---\r\n\r\n## Internationalization\r\n\r\nAskGem is **English-First** at the SDK/System level for maximum model reliability, but the entire user interface supports 8 languages:\r\n\r\n| Code | Language | File |\r\n|---|---|---|\r\n| `en` | English (Standard) | `en.json` |\r\n| `es` | Español | `es.json` |\r\n| `fr` | Français | `fr.json` |\r\n| `pt` | Português | `pt.json` |\r\n| `de` | Deutsch | `de.json` |\r\n| `it` | Italiano | `it.json` |\r\n| `ja` | 日本語 | `ja.json` |\r\n| `zh` | 中文 (简体) | `zh.json` |\r\n\r\n---\r\n\r\n## Repository Standard\r\n\r\n`askgem.py` is now the reference repo for structure, hygiene, and architecture conventions in this workspace.\r\n\r\nSee [STANDARD.md](STANDARD.md) for the operating standard to apply across the other repositories.\r\n\r\n---\r\n\r\n## Roadmap\r\n\r\n| Version | Theme | Status |\r\n|---|---|---|\r\n| `v0.14.0`| Stability, Renderer Polish | ✅ Done |\r\n| `v0.15.0`| **Kwisatz Haderach** - LSP Integration | ✅ Done |\r\n| `v0.16.0`| **The Golden Path** - Professional Recovery | ✅ Done |\r\n| `v0.16.2`| **Stabilization** - Knowledge Optimization | ✅ Done |\r\n| `v0.17.0`| **Shai-Hulud** - Scalable Memory | 📋 Planned |\r\n| `v1.0.0` | Stable Release — Full docs, PyPI publication | 📋 Planned |\r\n\r\n---\r\n\r\n## License\r\n\r\nGNU General Public License v3.0 — see [LICENSE](LICENSE) for full terms.\r\n\r\nBuilt by [julesklord](https://github.com/julesklord).\r\n\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesklord%2Faskgem.py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjulesklord%2Faskgem.py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjulesklord%2Faskgem.py/lists"}