feat: Introduce Agent Task Command and Enhance UX

CHANGELOG.md

@@ -9,6 +9,31 @@ and this project aims to adhere to [Semantic Versioning](https://semver.org/spec
 
 _(Future changes will go here)_
 
+### Added
+
+- A new `agent_task` command for advanced, agent-based workflows, including clickable log entries and dynamic prompt updates. ([a69b80c](https://github.com/lacerbi/athanor/commit/a69b80c), [94aa97f](https://github.com/lacerbi/athanor/commit/94aa97f), [67ba73e](https://github.com/lacerbi/athanor/commit/67ba73e))
+- Enhanced `CREATE` file operation to allow overwriting existing files with a clear user warning. ([4e2027a](https://github.com/lacerbi/athanor/commit/4e2027a))
+- Listeners for `Ctrl+C`/`Ctrl+V` to improve clipboard interaction. ([7743aa8](https://github.com/lacerbi/athanor/commit/7743aa8))
+
+### Changed
+
+- Updated the agentic architect prompt for better performance. ([4e2027a](https://github.com/lacerbi/athanor/commit/4e2027a))
+
+### Fixed
+
+- Corrected paste behavior within the application. ([bfb3a3e](https://github.com/lacerbi/athanor/commit/bfb3a3e))
+- Added `ELECTRON_USE_DESKTOP_GL` environment flag to mitigate potential rendering issues. ([87ba6e3](https://github.com/lacerbi/athanor/commit/87ba6e3))
+- Minor text clarifications in the Review panel for better usability. ([ef6d6d5](https://github.com/lacerbi/athanor/commit/ef6d6d5))
+
+### Documentation
+
+- Added `GEMINI.md` and updated `CLAUDE.md` to provide guidance for different AI models. ([b2f15cb](https://github.com/lacerbi/athanor/commit/b2f15cb), [fdc032d](https://github.com/lacerbi/athanor/commit/fdc032d))
+- Clarified that Prettier is used for code formatting. ([c02b34a](https://github.com/lacerbi/athanor/commit/c02b34a))
+
+### Tests
+
+- Fixed and updated unit tests to align with the new `agent_task` command. ([8050594](https://github.com/lacerbi/athanor/commit/8050594))
+
 ## [0.7.7] - 2025-07-01
 
 ### Added

CLAUDE.md

@@ -14,7 +14,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 - `npm test` - Run Jest unit tests (includes both main and renderer process tests)
 - `npm run test:watch` - Run tests in watch mode
-- `npm run lint` - Run ESLint on TypeScript/React code
+- `npm run lint` - **Note: Currently non-functional** due to ESLint configuration incompatibility (`.eslintrc.js` uses old format incompatible with ESLint 9+). Prettier is used for code formatting.
 
 **Platform-specific builds:**
 
@@ -39,6 +39,11 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 - `RelevanceEngineService.ts` - Intelligent context discovery using multiple heuristics
 - `ProjectGraphService.ts` - Background project analysis and dependency mapping
 - `GitService.ts` - Git repository analysis for relevance scoring
+- `UserActivityService.ts` - Real-time file activity tracking for relevance signals
+- `SettingsService.ts` - Project and application settings management
+- `ShellService.ts` - Terminal/CLI session management with persistent PTY sessions
+- `TaskAnalysisUtils.ts` - Task description analysis and keyword extraction
+- `DependencyResolver.ts` / `DependencyScanner.ts` - Language-aware dependency analysis
 
 ### Critical File System Patterns
 
@@ -63,6 +68,10 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 - `promptStore.ts` - Prompt templates and variants
 - `taskStore.ts` - Task templates and variants
 - `applyChangesStore.ts` - AI-generated file change management
+- `settingsStore.ts` - Project and application settings state
+- `logStore.ts` - Application log management with interactive entries
+- `commandStore.ts` - Clipboard and command validation state
+- `cliStore.ts` - Terminal session state management
 
 ### Project Structure Insights
 
@@ -71,18 +80,47 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 - Relevance Engine uses Git history, dependencies, file mentions, and user activity
 - Project analysis runs in background worker thread (`projectAnalysisWorker.ts`)
 - Results cached in `.ath_materials/project_graph.json`
+- Two-phase scoring engine with multiple heuristics for relevance
+- Automatic re-analysis when file changes are detected after inactivity
 
 **AI Integration:**
 
 - Optional direct API integration via secure storage (`electron/modules/secure-api-storage/`)
 - Primary workflow: copy prompts to external AI, paste responses back
 - XML command parsing for applying AI-generated changes
+- Modular LLM provider system (`electron/modules/llm/`) supporting:
+  - Anthropic Claude API
+  - OpenAI GPT models
+  - Google Gemini models
+  - Mistral models (API key storage only)
+- Type-safe IPC channels for LLM operations
+- Extensive model configuration and client adapters
 
 **File Management:**
 
 - Supports `.athignore` and `.gitignore` patterns
 - Chokidar file watchers for real-time updates
 - Path normalization via `PathUtils.ts`
+- Agent task creation in `.ath_materials` directory
+
+**CLI/Terminal Support:**
+
+- Integrated terminal via `node-pty` and `xterm.js`
+- Multi-session support with persistent terminals
+- Platform-specific shell detection (PowerShell on Windows, zsh/bash on Unix)
+- Managed by `ShellService.ts` and `cliStore.ts`
+
+**Additional Features:**
+
+- **Tooltips**: Contextual help throughout the UI via hover tooltips
+- **Drag and Drop**: File paths can be dragged from explorer to task/context areas
+- **Context Suggestions**: Automatic context suggestions based on task content
+- **Preset Tasks**: Pre-defined task templates loaded from `task_*.xml` files
+- **Token Budgeting**: Intelligent file inclusion based on token limits
+- **Smart Preview**: Configurable preview of file contents in prompts
+- **Documentation Format**: Multiple format options for file inclusion
+- **Ignore Rules**: Advanced pattern matching with `.athignore` and `.gitignore`
+- **Project Settings**: Stored in `.ath_materials/project_settings.json`
 
 ## Testing Considerations
 
@@ -108,6 +146,22 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 4. Update `src/types/global.d.ts` type definitions
 5. Implement UI-level operations in `fileSystemService.ts`
 
+**When adding new IPC handlers:**
+
+1. Create handler functions in appropriate file in `electron/handlers/`
+2. Export from `ipcHandlers.ts` for registration
+3. Add corresponding methods to `preload.ts`
+4. Update type definitions in `src/types/global.d.ts`
+
+**Important UI Patterns:**
+
+- **Left Panel**: File explorer with context menus and ignore functionality
+- **Right Panel**: Task tabs, file viewer, and Apply Changes panel
+- **Bottom Panel**: Log viewer with clickable entries for debugging
+- **Action Panel**: Controls for prompt generation, preset tasks, and settings toggles
+- **Task Templates**: XML-based templates in `resources/prompts/`
+- **Prompt Variants**: Context menu for switching between prompt modes (Query, Coder, Architect)
+
 **Security considerations:**
 
 - Never bypass IPC bridge for file operations
@@ -117,7 +171,7 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 **Code style:**
 
 - TypeScript 5+ with strict typing
-- ESLint + Prettier configuration
+- Prettier for code formatting (ESLint config exists but is incompatible with ESLint 9+)
 - TailwindCSS 3 + Material-UI components
 - Conventional Commits for commit messages
 
@@ -131,3 +185,8 @@ Athanor is an Electron desktop application for AI-assisted development workflows
 - **ignore** - .gitignore/.athignore parsing
 - **js-tiktoken** - Token counting for prompts
 - **Jest + ts-jest** - Testing framework
+- **@anthropic-ai/sdk** - Anthropic Claude API integration
+- **openai** - OpenAI API integration
+- **@google/genai** - Google Gemini API integration
+- **node-pty** - Terminal emulation support
+- **xterm & xterm-addon-fit** - Terminal rendering in UI

GEMINI.md

@@ -0,0 +1,192 @@
+# GEMINI.md
+
+This file provides guidance to Gemini CLI when working with code in this repository.
+
+## Essential Commands
+
+**Development:**
+
+- `npm run package` - **(Standard)** Build a local production application (in `out/`). This is the recommended way to test changes.
+- `npm start` or `npm run dev` - **(Deprecated for testing)** Start development mode with hot reload. Do not use.
+- `npm run make` - Unsupported. Do not use.
+
+**Testing & Quality:**
+
+- `npm test` - Run Jest unit tests (includes both main and renderer process tests)
+- `npm run test:watch` - Run tests in watch mode
+- `npm run lint` - **Note: Currently non-functional** due to ESLint configuration incompatibility (`.eslintrc.js` uses old format incompatible with ESLint 9+). Prettier is used for code formatting.
+
+**Platform-specific builds:**
+
+- `npm run build:win` - Build for Windows
+- `npm run build:linux` - Build for Linux
+
+## Architecture Overview
+
+Athanor is an Electron desktop application for AI-assisted development workflows. It helps developers create context-rich prompts and apply AI-generated changes to codebases.
+
+### Core Architecture Principles
+
+**Main/Renderer Separation:**
+
+- **Main Process** (`electron/`): File system operations, Git integration, project analysis
+- **Renderer Process** (`src/`): React UI, state management with Zustand
+- **IPC Communication**: Secure bridge via `preload.ts` and typed in `src/types/global.d.ts`
+
+**Key Services:**
+
+- `FileService.ts` - Central file system operations manager (main process)
+- `RelevanceEngineService.ts` - Intelligent context discovery using multiple heuristics
+- `ProjectGraphService.ts` - Background project analysis and dependency mapping
+- `GitService.ts` - Git repository analysis for relevance scoring
+- `UserActivityService.ts` - Real-time file activity tracking for relevance signals
+- `SettingsService.ts` - Project and application settings management
+- `ShellService.ts` - Terminal/CLI session management with persistent PTY sessions
+- `TaskAnalysisUtils.ts` - Task description analysis and keyword extraction
+- `DependencyResolver.ts` / `DependencyScanner.ts` - Language-aware dependency analysis
+
+### Critical File System Patterns
+
+**Always use proper abstraction layers:**
+
+- Main process: Use `FileService.ts` singleton for all file operations
+- Renderer process: Use `fileSystemService.ts` for UI-related file operations
+- Never bypass IPC for file operations from renderer
+
+**Global type definitions:**
+
+- `src/types/global.d.ts` - Extends window interface and defines core types
+- Must be updated when modifying IPC method signatures
+
+### State Management
+
+**Zustand stores in `src/stores/`:**
+
+- `fileSystemStore.ts` - Selected files, file tree, preview state
+- `workbenchStore.ts` - Multi-tab task management
+- `contextStore.ts` - Intelligent context builder state
+- `promptStore.ts` - Prompt templates and variants
+- `taskStore.ts` - Task templates and variants
+- `applyChangesStore.ts` - AI-generated file change management
+- `settingsStore.ts` - Project and application settings state
+- `logStore.ts` - Application log management with interactive entries
+- `commandStore.ts` - Clipboard and command validation state
+- `cliStore.ts` - Terminal session state management
+
+### Project Structure Insights
+
+**Core Intelligence:**
+
+- Relevance Engine uses Git history, dependencies, file mentions, and user activity
+- Project analysis runs in background worker thread (`projectAnalysisWorker.ts`)
+- Results cached in `.ath_materials/project_graph.json`
+- Two-phase scoring engine with multiple heuristics for relevance
+- Automatic re-analysis when file changes are detected after inactivity
+
+**AI Integration:**
+
+- Optional direct API integration via secure storage (`electron/modules/secure-api-storage/`)
+- Primary workflow: copy prompts to external AI, paste responses back
+- XML command parsing for applying AI-generated changes
+- Modular LLM provider system (`electron/modules/llm/`) supporting:
+  - Anthropic Claude API
+  - OpenAI GPT models
+  - Google Gemini models
+  - Mistral models (API key storage only)
+- Type-safe IPC channels for LLM operations
+- Extensive model configuration and client adapters
+
+**File Management:**
+
+- Supports `.athignore` and `.gitignore` patterns
+- Chokidar file watchers for real-time updates
+- Path normalization via `PathUtils.ts`
+- Agent task creation in `.ath_materials` directory
+
+**CLI/Terminal Support:**
+
+- Integrated terminal via `node-pty` and `xterm.js`
+- Multi-session support with persistent terminals
+- Platform-specific shell detection (PowerShell on Windows, zsh/bash on Unix)
+- Managed by `ShellService.ts` and `cliStore.ts`
+
+**Additional Features:**
+
+- **Tooltips**: Contextual help throughout the UI via hover tooltips
+- **Drag and Drop**: File paths can be dragged from explorer to task/context areas
+- **Context Suggestions**: Automatic context suggestions based on task content
+- **Preset Tasks**: Pre-defined task templates loaded from `task_*.xml` files
+- **Token Budgeting**: Intelligent file inclusion based on token limits
+- **Smart Preview**: Configurable preview of file contents in prompts
+- **Documentation Format**: Multiple format options for file inclusion
+- **Ignore Rules**: Advanced pattern matching with `.athignore` and `.gitignore`
+- **Project Settings**: Stored in `.ath_materials/project_settings.json`
+
+## Testing Considerations
+
+**Mocking Strategy:**
+
+- Electron modules mocked via `tests/__mocks__/electron.ts`
+- File system operations mocked for isolation
+- Tests co-located with source files (e.g., `FileService.test.ts`)
+
+**Test Environment:**
+
+- Jest with Node.js environment for main process
+- ts-jest for TypeScript compilation
+- Tests cover both main and renderer processes
+
+## Development Guidelines
+
+**When adding file system features:**
+
+1. Add core functionality to `FileService.ts` or `PathUtils.ts`
+2. Create IPC handlers in `handlers/` directory
+3. Update `preload.ts` interface methods
+4. Update `src/types/global.d.ts` type definitions
+5. Implement UI-level operations in `fileSystemService.ts`
+
+**When adding new IPC handlers:**
+
+1. Create handler functions in appropriate file in `electron/handlers/`
+2. Export from `ipcHandlers.ts` for registration
+3. Add corresponding methods to `preload.ts`
+4. Update type definitions in `src/types/global.d.ts`
+
+**Important UI Patterns:**
+
+- **Left Panel**: File explorer with context menus and ignore functionality
+- **Right Panel**: Task tabs, file viewer, and Apply Changes panel
+- **Bottom Panel**: Log viewer with clickable entries for debugging
+- **Action Panel**: Controls for prompt generation, preset tasks, and settings toggles
+- **Task Templates**: XML-based templates in `resources/prompts/`
+- **Prompt Variants**: Context menu for switching between prompt modes (Query, Coder, Architect)
+
+**Security considerations:**
+
+- Never bypass IPC bridge for file operations
+- Validate all paths in main process handlers
+- Use secure API key storage for LLM integration
+
+**Code style:**
+
+- TypeScript 5+ with strict typing
+- Prettier for code formatting (ESLint config exists but is incompatible with ESLint 9+)
+- TailwindCSS 3 + Material-UI components
+- Conventional Commits for commit messages
+
+## Key Dependencies
+
+- **Electron 33+** - Desktop app framework
+- **React 19+** - UI framework
+- **TypeScript 5+** - Type safety
+- **Zustand** - State management
+- **Chokidar** - File watching
+- **ignore** - .gitignore/.athignore parsing
+- **js-tiktoken** - Token counting for prompts
+- **Jest + ts-jest** - Testing framework
+- **@anthropic-ai/sdk** - Anthropic Claude API integration
+- **openai** - OpenAI API integration
+- **@google/genai** - Google Gemini API integration
+- **node-pty** - Terminal emulation support
+- **xterm & xterm-addon-fit** - Terminal rendering in UI

PROJECT.md

@@ -158,7 +158,8 @@ Athanor follows Electron's recommended **“secure by default”** pattern, sepa
 - **Webpack & electron-forge**: Build, package, and run the Electron application.
 - **TailwindCSS 3 + Lucide Icons**: Provides a flexible styling system and icon library for a clean UI.
 - **Material-UI (MUI) 5**: Partially integrated for certain UI elements (used in some components).
-- **ESLint / Prettier**: Linting & formatting for consistent code style.
+- **Prettier**: Code formatting for consistent style (configured via `.prettierrc`).
+- **ESLint**: Currently non-functional due to incompatible configuration format (`.eslintrc.js` uses old format incompatible with ESLint 9+). The `npm run lint` command will not work properly.
 - **Jest & ts-jest**: Provide the unit testing framework. Tests are typically colocated with the source code they validate (e.g., `FileService.test.ts` alongside `FileService.ts`).
 - **Testing Mocks**: Key dependencies, including Electron itself (via `tests/__mocks__/electron.ts`) and Node.js modules like `fs/promises`, are mocked to ensure isolated and reliable unit tests.
 

docs/TROUBLESHOOTING.md

@@ -70,10 +70,32 @@ If you're running Athanor in WSL, installing `libsecret` alone is not sufficient
 
 </details>
 
----
-
-**IMPORTANT FINAL STEP (ALL DISTRIBUTIONS):**
+#### **IMPORTANT FINAL STEP (ALL DISTRIBUTIONS):**
 
 After the installation is complete, **you must log out and log back in**, or simply restart your computer. This ensures the newly installed keyring service is active and available to all applications, including Athanor.
 
 After restarting, when you first try to save a key, your system might prompt you to create a new default keyring and set a password for it. This is a one-time setup. Once completed, Athanor will be able to store API keys securely.
+
+---
+
+## Linux/WSL Graphics Issue (Blank Screen)
+
+### Problem: The application window is blank or black on startup
+
+When launching Athanor on certain Linux desktop environments or within the Windows Subsystem for Linux (WSL), the application may start, but the window remains completely blank. You may see a black or white screen instead of the user interface.
+
+### Cause
+
+This issue typically occurs when Electron, the framework used by Athanor, fails to automatically select the correct graphics rendering backend for your system. The default choice may be incompatible with your graphics driver setup, especially within the virtualized environment of WSL.
+
+### Solution
+
+You can resolve this by instructing Athanor to use a specific, more compatible graphics backend called "Desktop OpenGL." This is done by setting an environment variable before launching the application.
+
+1.  Open your shell's configuration file. This is usually `~/.bashrc`, `~/.zshrc`, or `~/.profile`, depending on your shell.
+2.  Add the following line to the end of the file:
+    ```bash
+    export ELECTRON_USE_DESKTOP_GL=1
+    ```
+3.  Save the file and restart your terminal, or run `source ~/.bashrc` (or the equivalent for your shell) to apply the changes.
+4.  Launch Athanor from the terminal. It should now start correctly with the UI visible.