ai-assist

# ai-assist - AI Assistant for Managers

An intelligent AI assistant powered by Claude, Skills and MCP (Model Context Protocol) that helps managers with periodic automated monitoring and interactive querying.

Works with MCP servers like:
- [DCI MCP Server](https://github.com/redhat-community-ai-tools/dci-mcp-server) for DCI and Jira
- [Second Brain](https://github.com/flepied/second-brain-agent) for personal notes
- Any other MCP-compatible server

Works with skills like:

- [pdf](https://github.com/anthropics/skills/blob/main/skills/pdf/SKILL.md)
- [markdown-converter](https://github.com/intellectronica/agent-skills/blob/main/skills/markdown-converter/SKILL.md)
- Any other [skills](https://skills.sh/)

## Features

- 🤖 **AI-Powered**: Claude Sonnet 4.5 for intelligent analysis
- 🔌 **MCP Integration**: Connect to any MCP server for tools and data
- 📊 **Monitoring**: Automated scheduled checks with smart notifications
- ⏰ **Scheduled Actions**: One-shot future actions with notifications
- 💬 **Interactive Mode**: Rich TUI with streaming responses and history
- 🧠 **Knowledge Graph**: Temporal database tracking entities and changes
- 📝 **Report Generation**: Create and manage markdown reports
- ⚡ **Hot Reload**: Schedule changes take effect immediately
- 🚀 **Agent Skills**: Install specialized skills following [agentskills.io](https://agentskills.io/) specification
- 🔄 **AWL Workflows**: Script multi-step agent workflows with conditionals, loops, and variable propagation

## Quick Start

### Prerequisites

Choose ONE authentication method:
- **Vertex AI** (Google Cloud): Enterprise/company Claude access
- **Direct API** (Anthropic): Personal use with free tier

### Installation

First, install [uv](https://docs.astral.sh/uv/getting-started/installation/) if you don't have it:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Then install ai-assist:

```bash
git clone https://github.com/fredericlepied/ai-assist
cd ai-assist
uv sync
```

### Configuration

```bash
cp .env.example .env
# Edit .env with your credentials
```

**Vertex AI** (Google Cloud):
```bash
export ANTHROPIC_VERTEX_PROJECT_ID='your-gcp-project-id'
gcloud auth application-default login
```

**Direct API** (Anthropic - free tier available):
```bash
export ANTHROPIC_API_KEY='sk-ant-...'  # Get from console.anthropic.com
```

📖 **Vertex AI setup:** See [VERTEX_AI_SETUP.md](VERTEX_AI_SETUP.md)

**Personalization** (Optional):

Customize the assistant's personality and communication style:

```bash
uv run ai-assist /identity-init  # Create template
uv run ai-assist /identity-show  # View current settings
```

Edit `~/.ai-assist/identity.yaml` to configure:
- Your name, role, and organization
- Assistant nickname and personality
- Communication preferences (formality, verbosity, emoji usage)
- Work context for better assistance

📖 **Full identity guide:** See [docs/IDENTITY.md](docs/IDENTITY.md)

**Logging** (Optional):

Control logging verbosity for debugging and monitoring:

```bash
# File logging level (default: INFO)
export AI_ASSIST_LOG_LEVEL=DEBUG

# Console logging level (default: WARNING)
export AI_ASSIST_CONSOLE_LOG_LEVEL=INFO
```

Logs are written to: `~/.ai-assist/logs/ai-assist-YYYY-MM-DD.log`

📖 **Logging guide:** See [docs/LOGGING.md](docs/LOGGING.md)

## Usage

### Interactive Mode

Chat with the assistant using a rich terminal interface:

```bash
uv run ai-assist /interactive
# or simply
uv run ai-assist
```

**Features:**
- 🎨 Rich markdown formatting with syntax highlighting
- 📝 Multi-line editing (Esc-Enter for newlines)
- 📚 Command history with search (Ctrl-R)
- ⌨️ Tab completion for commands
- ⚡ Streaming responses in real-time
- 🛑 Cancel streaming with Escape key
- 🧠 Conversation memory with persistent storage in knowledge graph
- 💾 Nightly self-reflection extracts knowledge from conversations

**Built-in Commands:**
- `/status` - Show statistics
- `/history` - Recent monitoring history
- `/clear` - Clear conversation memory
- `/clear-cache` - Clear response cache
- `/kg-save [on|off]` - Toggle knowledge graph auto-save
- `@no-kg <query>` - Suppress KG context injection for a single query
- `/kg-viz` - Visualize knowledge graph in browser
- `/prompts` - List available MCP prompts with arguments
- `/prompt-info <server/prompt>` - Show detailed prompt info
- `/skill/install <source>@<branch>` - Install an Agent Skill
- `/skill/uninstall <name>` - Uninstall an Agent Skill
- `/skill/list` - List installed Agent Skills
- `/skill/search <query>` - Search ClawHub and skills.sh registries
- `/skill/add_env <skill> <VAR>` - Allow an environment variable for a skill's scripts
- `/skill/remove_env <skill> <VAR>` - Remove an allowed env var from a skill
- `/skill/list_env [skill]` - Show allowed env vars for skills
- `/mcp/restart <server>` - Restart an MCP server (picks up binary updates)
- `/help` - Show help
- `/exit` or `/quit` - Exit

**Security:**

When a command is not on the allowlist, the assistant prompts for confirmation:

```
Allow? [y/N/a(lways)]
```

- **y** - Allow once
- **N** - Deny (default)
- **a(lways)** - Allow and permanently add to the allowlist

**Example queries:**
```
What are the latest failing DCI jobs?
Show me critical Jira tickets in the CILAB project
Find OpenShift 4.19 jobs that failed in the last week
```

### MCP Prompts

Execute MCP server prompts directly with slash commands:

```bash
# In interactive mode
/dci/rca         # Run RCA prompt from dci server
/prompts         # List all available prompts
```

MCP prompts can request arguments interactively and automatically execute with streaming results.

### Agent Skills

Install specialized skills following the [agentskills.io](https://agentskills.io) specification:

```bash
# In interactive mode
/skill/install anthropics/skills/skills/pdf@main     # Install PDF skill from GitHub
/skill/install /path/to/my-skill@main                # Install local skill
/skill/list                                          # List installed skills
/skill/uninstall pdf                                 # Uninstall skill
/skill/search pdf                                    # Search ClawHub and skills.sh
```

**What are Agent Skills?**
- Specialized instructions for Claude following agentskills.io standard
- Automatically loaded into system prompt (no activation needed)
- Can include scripts, references, and assets

📖 **Creating personal skills:** See [docs/PERSONAL_SKILLS.md](docs/PERSONAL_SKILLS.md)
- Persistent across sessions

**Example skills:**
- PDF processing (extract text, fill forms, merge)
- DOCX manipulation
- Custom workflow automation
- Domain-specific expertise

**Creating your own skills:**
```bash
mkdir -p my-skill
cat > my-skill/SKILL.md << 'EOF'
---
name: my-skill
description: My custom skill
---

# My Skill Instructions

When the user asks for X, do Y...
EOF

uv run ai-assist
You> /skill/install /path/to/my-skill@main
```

📖 **Skill specification:** See [agentskills.io/specification](https://agentskills.io/specification)

#### Script Execution (Advanced)

Skills can include executable scripts in a `scripts/` directory. **Script execution is disabled by default for security.**

**Enable script execution:**
```bash
export AI_ASSIST_ALLOW_SCRIPT_EXECUTION=true
uv run ai-assist
```

**Security requirements:**
- Skills must declare permission in SKILL.md:
  ```yaml
  allowed-tools: "internal__execute_skill_script"
  ```
- Scripts run in a sandboxed environment:
  - No access to API keys or secrets (environment filtered)
  - Per-skill env var allowlist via `/skill/add_env` (persisted in `~/.ai-assist/skill_env.json`)
  - 30-second timeout limit
  - Output limited to 20KB
  - Directory traversal blocked
  - No shell injection possible

**Example skill with script:**
```markdown
---
name: pdf-tools
description: PDF processing utilities
compatibility: Requires python3, python3-pypdf
allowed-tools: "internal__execute_skill_script"
---

# PDF Tools

Run `scripts/check_fillable_field

[truncated…]