# CODEBASE INDEX MAP | Generated: 2026-09-20 15:56 | Workspace: fetch | Path: ~/.config/fetch
# Active symbols and structural connections mapped in the local index.
# -----------------------------------------------------------------------------------------
# Codebase Modules & Active Architecture:
#   ├── .env                     - ~/.config/fetch/.env
#   ├── .gitignore               - Secrets & Credentials
#   ├── .last_cloud_key.txt      - GEMINI_API_KEY
#   ├── .openrouter_cache_v2.json - {
#   ├── .request_log
#   ├── .state.json              - {
#   ├── CONTRIBUTING.md          - Contributing to Py-Agent
#   ├── LICENSE                  - MODIFIED MIT LICENSE (NON-COMMERCIAL / NO BUSINESS USE)
#   ├── README.md                - <div align="center">
#   ├── RELEASE-NOTES.md         - <div align="center">
#   ├── SECURITY.md              - Security Policy
#   ├── ai-agent.py              - Py Agent [j5onrf] [v0.9.9.36] - Main CLI Runtime, Workspace Agent & Command Dispatcher [Production R
#   ├── ai-context.md            - Py-Agent Config
#   ├── ai-hook.sh               - Production Py-Agent Shell Hook v0.9.9.28 (Hardened & Production Ready)
#   ├── logo.svg                 - <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 220 220" width="100%" height="100%">
#   ├── server.pem               - -----BEGIN PRIVATE KEY-----
#   ├── modules/Readme.md        - Private-First
#   ├── modules/agent_adapters.py - Tool Format Adapters & Self-Healing Parser for Small-Models [Production Ready]
#   ├── modules/agent_cloud.py   - Dynamic Cloud Cascade Engine - Top-down .env provider API priority with infinite CUSTOM* support [Pr
#   ├── modules/agent_context.py - Context Search & Indexing Engine - Jaccard intent matching [Production Ready]
#   ├── modules/agent_core.py    - Core Module - Streaming SSE, dynamic tool execution, & Rich rendering [Production Ready]
#   ├── modules/agent_ipython.py - Local-AI Standalone IPython Kernel & RLM Harness Module [Production Ready]
#   ├── modules/agent_memories.py - Open Knowledge Format (OKF) Project Memory Manager [Production Ready]
#   ├── modules/agent_sessions.py - SQLite-backed session, checkpoint, and turn logger with sub-agent registry [Production Ready]
#   ├── modules/agent_skills.py  - Unified library & executable for static, dynamic, universal YAML, and on-demand skills [Production R
#   ├── modules/agent_tools.py   - Native Tool Engine - Handles file editing, search, commands, & graph intelligence [Production Ready]
#   ├── modules/agent_tts.py     - Local-AI Kokoro Text-to-Speech Module [Production Ready]
#   ├── modules/agent_tui.py     - Production Minimal Textual TUI for Py Agent Engine [Production Ready]
#   ├── modules/agent_tui_async.py - Asynchronous uvloop background services for Local-AI Agent TUI [Production Ready]
#   ├── modules/agent_ui.py      - UI Module - Spinners, session boxes, and interactive menus [Production Ready]
#   ├── modules/agent_usage.py   - Unified Token Usage, Spend Ledger & Speed Tracker [Production Ready]
#   ├── modules/agent_voice.py   - Local-AI Standalone Voice to Text Module [Production Ready]
#   ├── modules/chat             - Unified Agentic Brainstorm, Thinking & Follow-up Recommendation Engine [Production Ready]
#   └── modules/model-select.py  - Streamlined TUI Model Selector driven by Local/HF, Generic Custom 2, Google Gemini & OpenRouter [Pro
# -----------------------------------------------------------------------------------------
[file:.gitignore] sum:Secrets & Credentials
[markdown:CONTRIBUTING.md] title:Contributing to Py-Agent
[file:LICENSE] sum:MODIFIED MIT LICENSE (NON-COMMERCIAL / NO BUSINESS USE)
[markdown:README.md] title:1. Install dependencies (Arch/CachyOS or pip) | links:ai-context.md
[markdown:RELEASE-NOTES.md] title:RELEASE-NOTES
[markdown:SECURITY.md] title:Security Policy
[python:ai-agent.py] imp:agent_context,agent_core,agent_ipython,agent_memories,agent_sessions,agent_skills,agent_tts,agent_ui,agent_voice,contextlib,json,os,re,readline,shutil,sqlite3,subprocess,sys,time,typing | fn:load_env_file,_show_transient_status,_clear_transient_status,workspace_db_counts,ensure_clean_agent_dir,_sweep_dead_session_locks,clean_exit,_launch_surface,_update_workspace_config,run_interactive_chat,run_direct_query,run_matching_search,main
[markdown:ai-context.md] title:Py-Agent Config
[shell:ai-hook.sh] sum:Production Py-Agent Shell Hook v0.9.9.28 (Hardened & Production Ready)
[image/svg:logo.svg] dim:100%x100% | size:1.6KB
[markdown:modules/Readme.md] title:Private-First | links:Readme.md
[python:modules/agent_adapters.py] imp:ast,json,os,re,time,typing | fn:normalize_params,_extract_balanced_json,heal_tool_call,heal_json_args,_extract_ast_python_calls,extract_fallback_tool_calls
[python:modules/agent_cloud.py] imp:os,re,typing | fn:_is_valid_key,get_active_configs
[python:modules/agent_context.py] imp:os,re,sys,typing | fn:tokenize,load_context_entries,jaccard_search,clean_tool_prefix
[python:modules/agent_core.py] imp:agent_adapters,agent_cloud,agent_ipython,agent_tools,agent_ui,agent_usage,base64,json,os,re,requests,rich,shutil,subprocess,sys,time,typing,urllib | cls:RichStreamer | fn:_get_console,_clean_sigint_handler,_get_img_config,describe_image_gemini,preprocess_multimodal_messages,_heal_tool_args,get_state,save_state,workspace_safe_name,is_calm_cli,run_mod,__init__,_stop_spinner,start,update,stop,_log_turn_usage,_process_stream_chunk,_calc_turn_tokens,_confirm_gate,_print_tool_output,_run_edit_tool,agentic_turn,_calc_msg_tokens,stream_response,get_accurate_token_count,show_memory_status,prune_history
[python:modules/agent_ipython.py] imp:IPython,agent_core,agent_memories,agent_tools,agent_ui,ast,builtins,collections,contextlib,io,os,signal,subprocess,sys,traceback,typing | cls:CellTimeoutError,MemorySDK,GraphSDK | fn:_timeout_handler,is_ipython_enabled,toggle_ipython_mode,bounded_repr,__init__,search,get_facts,add_fact,__init__,snippet,trace,blast_radius,search,architecture,delegate,_final_answer,_init_kernel_sdk,_is_outside,_check_boundary,safe_open,safe_listdir,_invalidate_module_cache,_read_file,_edit_file,_write_file,_list_dir,_search_code,_run_command,_save_memory_fn,inspect_ast_safety,run_cell,get_active_tools
[python:modules/agent_memories.py] imp:os,re,shutil,time,typing | fn:_get_memory_dir,parse_memory_file,get_memory_count,list_memories,get_memory_context,save_memory_file,clear_memories,add_fact,get_facts
[python:modules/agent_sessions.py] imp:agent_context,contextlib,glob,json,os,re,select,sqlite3,sys,termios,time,tty,typing | fn:tokenize,get_key,connect_db,cleanup_all_stale_locks,get_sub_agent_id,cleanup_sub_agent,init_db,save_checkpoint,rollback_checkpoint,log_turn,get_turns_count,clear_turns
[python:modules/agent_skills.py] imp:agent_context,agent_core,agent_ui,json,os,re,shutil,subprocess,sys,typing | fn:ensure_mysys_exists,parse_frontmatter,find_skill_file,load_skill_content,_exec_tool_cmd,run_local_tool,run_interactive_tool,get_system_context,load_skill_blueprints,run_skill_selector
[python:modules/agent_tools.py] imp:agent_core,agent_ipython,agent_ui,ast,collections,difflib,json,os,re,rich,shlex,subprocess,sys,typing,urllib | fn:get_modified_files,clear_session_tracking,_invalidate_module_cache,_is_calm,_safe_path,_is_outside_workspace,_check_command_security,_search_codebase,_generate_ast_skeleton,_resilient_replace,run_graph_cmd,run_tool,_in_bounds_gate,_security_gate
[python:modules/agent_tts.py] imp:agent_core,os,re,subprocess,threading | fn:stop_tts,is_tts_enabled,get_tts_speed,set_tts_speed,toggle_tts,clean_text_for_speech,speak_text,_run,speak_response
[python:modules/agent_tui.py] imp:agent_adapters,agent_cloud,agent_core,agent_ipython,agent_memories,agent_skills,agent_tools,agent_tts,agent_tui_async,agent_ui,agent_voice,base64,collections,contextlib,json,os,re,requests,rich,sqlite3,subprocess,sys,textual,threading,time,typing,uvloop | cls:FooterToggle,ImageButton,CloseCardButton,Message,AgentCommandProvider,LocalAITUI | fn:format_dir_path,format_model_name,copy_to_clipboard,_glimmer_tui_text,_format_tui_reasonix_text,on_click,on_click,on_click,__init__,update_content,render,search,command_sources,border_accent,is_dark_theme,watch_theme,__init__,on_unmount,_safe_remove_banner,notify,set_skill,set_mode,set_reasoning,action_prompt_image_url,on_key,refresh_db_counts,ensure_system_context,get_db_status_string,update_welcome_banner,compose,action_close_tips_card,on_mount,action_toggle_plan_build,on_input_changed,update_stats_ui,action_scroll_page_up,action_scroll_page_down,action_scroll_up,action_scroll_down,action_copy_last_response,action_copy_entire_chat,handle_view_file,handle_task_command,_sub,handle_slash_command,prompt_tui_confirm,_show,process_query_worker,on_input_submitted,disable_input,enable_input,action_stop_generation,update_sidebar_visibility,action_toggle_sidebar,update_footer_visibility,action_toggle_footer,action_toggle_compact,action_cycle_theme,action_toggle_reasoning,action_toggle_borders
[python:modules/agent_tui_async.py] imp:asyncio,json,os | fn:run_async_cmd,watch_workspace_changes,_get_dir_mtime,start_subagent_ipc_hub,handle_subagent_msg
[python:modules/agent_ui.py] imp:agent_cloud,agent_core,agent_skills,collections,json,os,re,rich,select,shutil,sys,termios,threading,time,tty,typing,urllib | cls:InlineSpinner,CalmBoatSpinner | fn:__init__,_get_theme_color,_glimmer,_spin,update,start,stop,__init__,update_context,update,_sail,start,stop,_read_fd,get_key,get_local_model_name,draw_session_box,confirm_tool,run_interactive_selection,show_help,select_workspace_profile
[python:modules/agent_usage.py] imp:json,os,sys,time,typing | fn:start,count_token,end,calculate_cost,record,turn_line
[python:modules/agent_voice.py] imp:agent_core,base64,http,json,os,re,socket,ssl,subprocess,sys,time,urllib | cls:VoiceHandler | fn:is_bridge_running,load_voice_env,transcribe_gemini,get_prompt_input,log_message,do_POST,do_GET,run_server,toggle_voice_bridge
[python:modules/chat] imp:agent_cloud,agent_ui,json,os,re,sys,urllib
[python:modules/model-select.py] imp:asyncio,atexit,json,os,re,select,shutil,sys,termios,time,tty,urllib | fn:cleanup_terminal,load_json,save_json,ensure_env_exists,load_env_vars,get_active_key_set,update_env_multiple,isolate_active_key,toggle_single_provider,toggle_independent_key,toggle_env_api_keys,parse_endpoint_url,async_fetch_remote,_fetch,async_get_key,_read,prompt_user_input,run_interactive_menu,filter_items,async_main,fmt
[markdown:plugins/Readme.md] title:Plugins: `plugins/`
[markdown:plugins/audio/Readme.md] title:Kokoro Neural Text-to-Speech & Selection Speaker Plugin
[shell:plugins/audio/koko-speak.sh] sum:High-Performance Kokoro Selection Speaker (RAM-disk execution)
[python:plugins/mcp/mcp_client.py] imp:json,os,select,sqlite3,subprocess,sys,time,typing | cls:MCPSession | fn:load_dotenv,load_servers_config,_ensure_sqlite_target,__init__,__enter__,__exit__,_send_rpc,_send_notification,_initialize,list_tools,call_tool,run_call,run_list,export_schemas,main
[json:plugins/mcp/servers.json] keys:servers
[python:plugins/pycode/bridge.py] imp:agent_adapters,agent_cloud,agent_core,agent_ipython,agent_memories,agent_sessions,agent_skills,agent_tools,agent_tts,json,os,requests,sys,threading,typing,uuid | fn:send_rpc_response,send_acp_chunk,detect_workspace_mode,assemble_system_prompt,handle_acp_prompt,main
[shell:plugins/pycode/launch.sh] sum:==============================================================================
[shell:plugins/pycode/setup.sh] sum:==============================================================================
[shell:plugins/webui/launch.sh] sum:==============================================================================
[python:plugins/webui/server.py] imp:agent_adapters,agent_core,agent_ipython,agent_memories,agent_sessions,agent_skills,agent_tools,agent_tts,gzip,http,json,os,re,requests,socketserver,sys,urllib | cls:OfficialWebUIProxyHandler,ThreadedProxyServer | fn:detect_workspace_mode,assemble_system_prompt,do_GET,do_OPTIONS,do_POST,log_message
[shell:setup/Ltiny.sh] sum:==============================================================================
[shell:setup/Mini2Bs.sh] sum:==========================================
[markdown:setup/Readme.md] title:Local Server Configuration & Model Selector (Universal CPU & GPU)
[shell:setup/kat.sh] sum:==============================================================================
[shell:setup/lfm2.sh] sum:Configuration
[python:setup/model-select-local.py] imp:asyncio,os,re,select,shutil,subprocess,sys,tempfile,termios,tty | fn:async_set_cpu_chill,async_set_cpu_balanced,get_current_running_model,async_stop_all_engines,launch_local_server,async_get_key,_read,draw_menu,async_main
[shell:setup/nex-n2.5.sh] sum:==========================================
[shell:setup/occamy.sh] sum:==============================================================================
[shell:setup/ornith.sh] sum:==============================================================================
[shell:setup/q2bu.sh] sum:==========================================
[shell:setup/tini.sh] sum:==============================================================================
[markdown:skills/Readme.md] title:Py-Agent Skills
[markdown:skills/hindsight.md] title:HINDSIGHT: RETROSPECTIVE & LESSON COMPILER
[markdown:skills/meta/brainstorm.md] title:[SKILL] brainstorm ---> brainstorm, lateral, creative, perspective, future, trends, macro
[markdown:skills/meta/follow-up.md] title:[SKILL] follow-up ---> follow-up, followup, question, mechanics, practical, compare
[markdown:skills/meta/thinking.md] title:[SKILL] thinking ---> thinking, think, analyze, next-steps, details, critique, risk
[markdown:skills/on-demand/caveman.md] title:[SKILL] Caveman Mode ---> caveman, talk like caveman, caveman-mode, less tokens, be brief
[markdown:skills/on-demand/chat/chat.md] title:chat
[markdown:skills/on-demand/i-have-adhd.md] title:ADHD Output Mode
[markdown:skills/on-demand/omarchy/capture.md] title:Screen Capture & Sharing Directives
[markdown:skills/on-demand/omarchy/contributing.md] title:Bug Reporting & Upstream Directives
[markdown:skills/on-demand/omarchy/diagnose-crash.md] title:Crash & Core Dump Diagnosis Directives
[markdown:skills/on-demand/omarchy/hooks.md] title:Automation Hooks Directives
[markdown:skills/on-demand/omarchy/hyprland.md] title:Hyprland Config Directives
[markdown:skills/on-demand/omarchy/omarchy.md] title:Omarchy System Directives
[markdown:skills/on-demand/omarchy/plugins.md] title:Shell, Bar & Plugins Directives
[markdown:skills/on-demand/omarchy/reporting.md] title:Reporting a Crash Upstream to Omarchy
[markdown:skills/on-demand/omarchy/theming.md] title:Theming & Appearance Directives
[markdown:skills/on-demand/pirate.md] title:[SKILL] Pirate Talk ---> pirate, talk like a pirate, pirate-talk, nautical, captain
[markdown:skills/on-demand/ponytail-py.md] title:[SKILL] Ponytail-Py ---> ponytail-py, senior python dev, yagni, minimal python, pythonic simplicity
[markdown:skills/on-demand/ponytail.md] title:[SKILL] Ponytail ---> ponytail, lazy senior dev, yagni, minimal code, simplify code
[markdown:skills/on-demand/pysmol.md] title:[SKILL] PySmol ---> pysmol, smol, smolagents, codeagent, python-loop, batch-code, in-memory-python, code-first
[markdown:skills/profiles/claude/pro.md] title:pro
[markdown:skills/profiles/custom/base.md] title:base
[markdown:skills/profiles/custom/deepseek.md] title:deepseek
[markdown:skills/profiles/custom/gemini.md] title:gemini
[markdown:skills/profiles/custom/katcoder.md] title:katcoder
[markdown:skills/profiles/custom/lfm2.md] title:lfm2
[markdown:skills/profiles/custom/lingtiny.md] title:lingtiny
[markdown:skills/profiles/custom/minicpm.md] title:minicpm
[markdown:skills/profiles/custom/nexn25.md] title:nexn25
[markdown:skills/profiles/custom/occamy (Copy).md] title:occamy (Copy)
[markdown:skills/profiles/custom/occamy.md] title:occamy
[markdown:skills/profiles/custom/ornith.md] title:ornith
[markdown:skills/profiles/custom/q2bu.md] title:q2bu
[markdown:skills/profiles/custom/sysadmin.md] title:sysadmin
[markdown:skills/profiles/custom/tielcoder.md] title:tielcoder
[markdown:skills/profiles/custom/tini-cybersec.md] title:tini-cybersec
[markdown:skills/profiles/hermes/pro.md] title:pro
[markdown:skills/profiles/pi/pro.md] title:pro
[markdown:skills/system/aur-audit.md] title:AUR PRE-INSTALL SECURITY AUDIT SKILL
[markdown:skills/system/mysys.md] title:SYSTEM ARCHITECTURE BLUEPRINT
[markdown:skills/system/security-audit.md] title:SYSTEM SECURITY AUDIT DIRECTIVES
[markdown:skills/system/system-optimizer.md] title:GENERAL LINUX DESKTOP OPTIMIZATION SKILL
[markdown:skills/system/update-inspector.md] title:ARCH LINUX UPGRADE DIRECTIVES
[markdown:skills/system_instructions.md] title:Global System Instructions
[markdown:tools/agentic/system/Readme.md] title:Readme
[file:tools/agentic/system/ai-commit] sum:ai-commit - High-Speed Minimalist Git Commit Generator
[file:tools/agentic/system/ai-status] sum:ai-status - Diagnostics for Py-Agent Cloud Models & Quotas v2.3.0
[file:tools/agentic/system/aur-audit] sum:aur-audit - Interactive Zero-Trust AUR Package Auditor v2.1.0
[file:tools/agentic/system/log-checker] sum:AI Log Triage & Diagnostics v2.5.0 (Zero-Config / High-Precision)
[file:tools/agentic/system/security-audit] sum:security-audit - Dynamic Security Profile Integrator & System Auditor v2.2.0
[file:tools/agentic/system/syscheck] sum:syscheck - Composite System Triage & Diagnostics Orchestrator
[file:tools/agentic/system/system-health] sum:system-health - Context-Aware Real-time Hardware Inspector
[file:tools/agentic/system/system-optimizer] sum:sysop - Dynamic Optimization & Hardware Profile Integrator v2.0.0
[file:tools/agentic/system/update-inspector] sum:AI Update Inspector - Universal Arch Linux
[python:tools/cheatsheet] imp:os,re,sys
[file:tools/email/.email] sum:--- Global fallback connection details ---
[markdown:tools/email/Readme.md] title:Email TUI Monitor: `email-agent`
[python:tools/email/email-agent] imp:agent_ui,concurrent,email,imaplib,os,re,sys | fn:load_email_config,clean_header,highlight_tags,fetch_single_account,fetch_emails,run_interactive_tui,main
[python:tools/evals/eval-agent] imp:agent_cloud,agent_core,agent_ui,ast,contextlib,io,json,os,re,rich,shutil,subprocess,sys,tempfile,time,urllib | fn:extract_python_code,run_single_test,get_current_model_info,main
[python:tools/evals/eval-stack] imp:agent_adapters,agent_cloud,agent_core,agent_ipython,agent_skills,agent_tools,agent_ui,contextlib,io,json,os,re,rich,select,shutil,subprocess,sys,tempfile,termios,threading,time,tty | cls:MinimalSpinner | fn:__init__,start,_spin,stop,_safe_read,list_available_profiles,select_profile_interactive,_get_k,resolve_dynamic_profile,get_current_model_info,_log_failure_trace,run_single_agentic_test,main
[python:tools/generate-profile] imp:glob,os,re,socket,subprocess,sys | fn:run
[markdown:tools/index-map/Readme.md] title:Codebase Mapping & Relational Knowledge Graph: `index-map`
[python:tools/index-map/index-map] imp:ast,fnmatch,json,os,re,sqlite3,struct,sys,time | cls:PythonGraphVisitor | fn:load_gitignore_patterns,should_ignore,is_binary,get_file_summary,__init__,visit_Import,visit_ImportFrom,visit_ClassDef,visit_FunctionDef,visit_AsyncFunctionDef,visit_any_func,parse_non_python_file,analyze_markdown_file,analyze_image_file,analyze_json_file,analyze_shell_file,analyze_generic_file,init_db,find_db_path,compile_ascii_tree,compile_flat_shorthand,run_indexing,search_symbols,extract_snippet,main
[python:tools/loop/ralph.py] imp:agent_core,agent_ui,argparse,os,re,sys,time | fn:_read_spec_file,_log_task_turn,is_task_complete,run_task_loop,main
[python:tools/new-project] imp:os,re,signal,sys | fn:prompt_tty,add_to_context_file,main
[python:tools/subsec/apps/media/media.py] imp:math,os,random,re,select,shutil,signal,subprocess,sys,termios,time,tty,unicodedata | cls:VisualizerPhysics,SystemAudio,PlayerManager | fn:strip_ansi,char_display_width,str_display_width,truncate_str_display,fmt_time,__init__,update,render_peak_equalizer,render_braille_spectrogram,render_stereo_vu_deck,make_vu_bar,render_oscilloscope,render_symmetrical_wings,render_cyber_matrix,generate_visualizer_panel,__init__,query,adjust,toggle_mute,__init__,parse_time,find_best_player,update,toggle,next,previous,seek,toggle_shuffle,cycle_loop,get_key_non_blocking,format_row,run_tuiamp,cleanup
[python:tools/subsec/apps/stopwatch/stopwatch.py] imp:math,os,re,select,shutil,signal,sys,termios,time,tty,unicodedata | fn:strip_ansi,char_display_width,str_display_width,truncate_str_display,fmt_time_high_res,fmt_delta,render_radar_sweep,render_chrono_pendulum,render_braille_wave,render_linear_pulse,render_matrix_stream,generate_visualizer_panel,get_key_non_blocking,format_row,run_stopwatch_tui,cleanup
[shell:tools/subsec/apps/stopwatch/stopwatch.sh] sum:Minimalist Pure Bash High-Resolution Stopwatch v2.0
[file:tools/subsec/hyprstate/gitcom] sum:Hyprland Workspace State Manager -- GitCom
[file:tools/subsec/hyprstate/work] sum:Hyprland Workspace State Manager -- Work
[python:tools/system-stack] imp:os,rich,select,shutil,subprocess,sys,termios,tty | fn:_get_tty_streams,check_mysys_drift,get_key_non_blocking,pause_terminal,draw_menu,run_target,main
[python:tools/test-agent] imp:agent_adapters,agent_cloud,agent_context,agent_core,agent_ipython,agent_memories,agent_sessions,agent_skills,agent_tools,agent_tts,agent_tui,agent_usage,ast,glob,importlib,json,os,py_compile,re,shutil,subprocess,sys,tempfile,time | fn:print_result