Geist Agent

Geist Agent is a custom AI agent built on the CrewAI framework, leveraging Typer to deliver a streamlined CLI (poltergeist). It currently has 5 commands. Seance allows you to ask questions about a code base, by indexing the project & uses BM25 or Jaccard to match keyword tokens before presenting that to your chosen LLM for summarization. Unveil provides an in depth summary of a codebase & includes a mermaid graph of the dependencies. Ward utilizes OSV to provide a security report of a codebase. Scry writes a research report on a topic that you provide. Doctor provides diagnostic information for troubleshooting & does initial setup for file placement.

---

Table of Contents

• Installation
• Configuration
• CLI Commands
• Reports

---

Installation

1. Fork the Repository: Click the "Fork" button to create your own copy.

2. Clone the Repository:

   git clone https://github.com/<your-username>/geist-agent.git
   cd geist-agent

   Replace <your-username> with your GitHub username or the correct repository URL.

3. Install uv: If you haven't already, install uv to manage dependencies:

   pip install uv

4. Install Dependencies: Use uv or pip to install the package. For development, install in editable mode:

   uv pip install -e .

   Alternatively, with pip:

   pip install -e .

5. Verify Installation: Run the diagnostics command to ensure everything is set up correctly:

   poltergeist doctor

   Connecting to your LLM will fail until you complete the configuration steps

---

Configuration

1. Run the Doctor Command: Run the following command to auto-generate the .geist directory and .env file in the appropriate location for your operating system. This will include placments for your API keys and extra setting controls for the commands:

   poltergeist doctor

   • Windows: C:\Users\<your-username>\.geist\.env
   • Linux/macOS: ~/.geist/.env

2. Add API Keys: Edit the generated .env file and add your API keys & configuration. Example:

   OPENAI_API_KEY=sk-xxxx
   MODEL=gpt-4o-mini
   API_BASE=https://api.openai.com
   

---

CLI Commands

The poltergeist CLI provides a range of commands for research, analysis, & diagnostics. Run the following to see all available commands:

poltergeist --help

Key Commands

• Analyze a Codebase: Summarize files & generate a dependency map for a codebase:

  poltergeist unveil --path .

• Research a Topic: Generate a Markdown report on a specified topic:

  poltergeist scry --topic "Your Topic"

• Run Diagnostics: Check your environment, Ollama setup, & reports directory:

  poltergeist doctor

• Generate Security Report: Write a security report using OSV (or their API if not installed):

  poltergeist ward --path .

• Index a Project: Index a project & use BM25 to find tokens so the LLM can answer questions about the codebase:

  poltergeist seance --path .

---

Reports

All reports generated by Geist Agent are saved in a dedicated directory for easy access:

• Windows: C:\Users\<your-username>\.geist\reports\
• Linux/macOS: ~/.geist/reports/

Reports are saved in Markdown format & include research summaries, codebase analyses, or diagnostic outputs, depending on the command used.