askgem 0.11.0

Autonomous AI Coding Agent powered by Google Gemini

askgem — Autonomous AI Coding Agent for the Terminal

---

WORK IN PROGRESS

---

askgem is a professional, autonomous coding agent that lives in your terminal. Powered by Google Gemini, 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

• How it works
• Features
• New in v0.11.0: Hyper-Context & Security
• Installation
• Configuration
• Usage
• Slash commands
• Safety model
• Architecture
• Development & Simulation
• Internationalization
• Roadmap
• Contributing
• License

---

How it works

askgem 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). askgem 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
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
manage_workspace	[v0.11.0] Detects and initializes local project knowledge bases

Workspace Isolation & Local Intelligence

AskGem now distinguishes between your Global Persona and your Project Context:

• Local Priority: If a .askgem/ folder exists in your project, it takes precedence for settings, memory, and history.
• Project Memory: Knowledge saved via manage_memory is stored within the project, preventing context leakage between repositories.
• Mission Persistence: Track specific dev-missions per project without cluttering your global space.

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.

Modern TUI Dashboard (Push-Layout)

A stable, high-performance interface built with the Textual framework, optimized for Windows:

• Real-time syntax-highlighted Markdown streaming.
• Reactive Sidebar showing live model context, current mission, and token stats.
• Command Palette with autocomplete suggestions for slash commands.
• Hidden output pane (F12) for detailed tool execution logs and debug info.

Persistent session history

Every conversation auto-saves to ~/.askgem/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.11.0: Hyper-Context & Security Hardening

The v0.11.0 release evolves AskGem from a reactive assistant into a proactive agent with hardened security:

1. AgentOrchestrator

The core logic has been centralized into an Orchestrator that manages the cognitive loop. It ensures that every tool execution is followed by a fresh observation and reasoning step, improving the reliability of multi-step coding tasks.

2. Project Blueprint (Hyper-Context)

AskGem no longer starts "blind". The ContextManager now performs an automatic recursive scan of your working directory on startup, identifying the tech stack and project architecture before you even ask your first question.

3. Trust Management System

Implemented a robust Directory Trust layer. AskGem will now ask for permission before accessing or modifying files outside of your workspace or explicit "Trusted Folders", preventing accidental system-wide modifications.

4. Windows Cross-Drive Hardening

Specific security guards for Windows users: prevents unauthorized operations across different drive letters (e.g., C: to D:) unless explicitly trusted.

---

Installation

Prerequisites

• Python 3.8 to 3.14 (v0.10.0 adds support for Python 3.14).
• A Google API Key — free at Google AI Studio.

From source (recommended)

git clone https://github.com/julesklord/askgem.py
cd askgem.py
python -m venv venv
# On Windows: venv\Scripts\activate
source venv/bin/activate
pip install -e ".[dev]"

---

Configuration

API key (Standardized)

askgem loads your key from these sources, in order:

1. Environment variable — GEMINI_API_KEY=your_key askgem (Preferred)
2. System Keyring — Secure storage via Windows Credential Manager or macOS Keychain (Recommended).
3. Saved file — ~/.askgem/settings.json (Local fallback).

On first launch without a key, askgem prompts interactively and saves it securely in your system's keyring.

Settings file

You can find the global configuration at ~/.askgem/settings.json.

---

🧠 Core Knowledge Hub (v0.13.0)

AskGem now features a Hierarchical Knowledge Hub, separating core behavioral rules from user-specific customizations. 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 (~/.askgem/*.md): Your cross-project technical preferences, API guidelines, or personal style.
3. 🚀 Project Hub (.askgem/*.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 AskGem'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

Stored at ~/.askgem/settings.json (POSIX) or %APPDATA%\askgem\settings.json (Windows):

{
    "model_name": "gemini-1.5-flash",
    "edit_mode": "manual"
}

Configuration paths

Path	Purpose
~/.askgem/settings.json	Model name, edit mode, and user preferences
~/.askgem/history/	Auto-saved session JSON files
~/.askgem/askgem.log	Debug log — tool execution events and retry details

---

Usage

Launch the agent:

askgem

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."
• Exploration: "Find all TODO comments in the project and group them by file."

Exiting

Type exit, quit, q, or press Ctrl+C.

---

Slash commands

Command	Description
/help	Show the full command reference and examples
/model <name>	Switch Gemini models mid-conversation (history preserved)
/mode [auto/manual]	Toggle between approving actions or automatic execution
/clear	Reset the context window to free up tokens without ending session
/usage	[v0.10.0] Show detailed token consumption and estimated USD cost
/stats	[v0.10.0] Summary of session accomplishments (messages, tools, files)
/stop	[v0.10.0] Interrupt the current generation immediately
/reset	[v0.10.0] Restart the entire session and reset all counters
/history [list/load/delete]	Manage saved conversation sessions
/trust [path]	[v0.11.0] Add a directory to the permanent whitelist
/untrust [path]	[v0.11.0] Remove a directory from the whitelist

---

Safety model

Always, regardless of mode (Sandboxed Environment):

• Trust Management Layer (v0.11.0): askgem now 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 (e.g., C: to G:) unless the target is explicitly trusted, preventing unintended system-wide access.
• Risk Analysis Engine: Powered by core/security.py, 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, fork bombs, world-writable chmod).
• Atomic Writing: edit_file uses a temporary file + rename strategy to prevent corruption.
• Automatic Backups: Every file modification creates a .bkp backup at <path>.bkp.
• Hard Timeouts: Shell commands have a strict 60-second execution limit.

---

Architecture

AskGem operates across three tightly decoupled layers enforcing strong logical boundaries. As of version 0.11.0, the system has evolved into an Orchestrated Architecture, where a central engine manages cognitive managers and security centinels.

High-Level System Diagram

flowchart TD
    CLI(["User execution (askgem)"]) --> Main(cli/main.py)
    Main --> Renderer(cli/renderer.py)
    Renderer <--> Orchestrator(agent/orchestrator.py: AgentOrchestrator)
    
    subgraph Cognitive_Layer [Cognitive Managers]
        Orchestrator --> Session[agent/core/session.py]
        Orchestrator --> Context[agent/core/context.py]
        Orchestrator --> Stream[agent/core/stream.py]
        Orchestrator --> Commands[agent/core/commands.py]
        Orchestrator --> Simulation[agent/core/simulation.py]
    end

    Orchestrator <--> GenAI[Google Gemini API]
    
    subgraph Security_Layer [Security & Trust Centinel]
        GenAI -. function calls .-> Trust[core/trust_manager.py]
        Trust --> SecurityCheck[core/security.py]
        SecurityCheck --> Tools(tools/)
    end

    Tools --> localDisk[(Local Workspace)]
    Context -. Blueprint .-> localDisk

Layer Breakdown

1. Presentation Layer (cli/): Handles the TUI lifecycle, interactive prompts, and real-time Markdown rendering via renderer.py.
2. Cognitive Layer (agent/): The "Brain". Powered by the AgentOrchestrator, it manages state, context blueprints, and mission tracking.
3. Security Layer (core/): The "Guard". Gathers risk analysis and whitelisting logic to ensure the agent never exceeds its authority.

Project Structure (v0.11.0)

askgem.py/
├── src/askgem/
│   ├── __init__.py              # Single source of truth for version (0.11.0)
│   ├── agent/
│   │   ├── orchestrator.py      # The Reasoning Brain — Thinking/Action/Observation
│   │   ├── schema.py            # Unified message and tool schemas
│   │   └── core/                # Cognitive Managers
│   │       ├── session.py       # API lifecycle, Retries and Error handling
│   │       ├── context.py       # Blueprint, Memory and Mission management
│   │       ├── commands.py      # Slash command handler
│   │       └── simulation.py    # Deterministic loop recording
│   ├── cli/
│   │   ├── main.py              # Entry point and session initialization
│   │   ├── renderer.py          # TUI interface and interactive prompts
│   ├── core/
│   │   ├── security.py          # Hardened safety engine
│   │   ├── trust_manager.py     # Directory trust whitelist control
│   │   ├── paths.py             # OS-agnostic path resolution (Workspace aware)
│   ├── tools/                   # Atomic agentic tools
│   └── locales/                 # i18n JSON data (8 languages supported)
├── tests/                       # 39+ reliable unit and integration tests
├── scripts/                     # Maintenance and diagnostic utilities
├── docs/                        # Rich documentation and assets
└── pyproject.toml

---

Development & Simulation

Setup

git clone https://github.com/julesklord/askgem.py
cd askgem.py
pip install -e ".[dev]"

Reliable Testing Protocol

AskGem v0.10.0 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 (39 tests)
ruff check src/ tests/ --fix    # auto-fix linting violations

---

Internationalization

AskGem is English-First at the SDK/System level for maximum model reliability, but the entire user interface supports 8 languages:

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

---

Roadmap

Version	Theme	Status
v0.10.0	Modular core, Stable TUI, Simulation, CD	✅ Done
v0.11.0	Workspaces, High-Security, Híper-Contexto	✅ Current
v1.0.0	Stable Release — Full docs, PyPI publication	📋 Planned
v1.1.0	Web tools — Google Search integration	📋 Planned
v2.0.0	LSP diagnostics and plugin ecosystem	🔵 Future

---

License

GNU General Public License v3.0 — see LICENSE for full terms.

Built with 💎 by julesklord.