YADA — Yet Another Developer Assistant

A terminal-based AI assistant that reclaims developer time by unifying fragmented context across Slack, GitHub, JIRA, code, and memory.

YADA solves a fundamental problem: critical information scattered across multiple tools consumes 10+ hours per week per developer. Instead of jumping between tools to find decisions, context, and discussions, YADA provides semantic search, cross-integration intelligence, and memory-first reasoning to answer questions faster and with more context.

Built on the OpenAI Agents SDK with production-grade architecture and careful prompt engineering to teach reasoning frameworks rather than hardcoded rules.

YADA is NOT a coding assistant that writes code for you. It does not generate code (beyond operational scripts), fix bugs, or refactor. Instead, it focuses on helping you find the context and information you need to code effectively. It helps you troubleshoot, research, and prepare, but the actual coding is still up to you.

YADA handles everything "around" coding—not the coding itself, but the activities that surround development work and consume most of your time:

• Daily Standup Prep: Pull JIRA tickets, format for standup.
• PR Review Context: Gather related Slack discussions, JIRA tickets.
• Code Investigation: Search code, Slack, GitHub for context.
• Status Reports: Compile updates from JIRA, GitHub.
• Design Research: Find past decisions, discussions, and reasoning.
• Onboarding New Team Members: Provide architecture overviews, key decisions, and context.
• Root Cause Analysis: Gather evidence from logs, code, discussions.

Real-World Examples:

• "Prepare my standup" → Pulled from JIRA with formatting ready
• "Find context for PR #456" → GitHub PR + Slack discussions + JIRA ticket all in one view
• "Search the codebase for authenticate function usages" → All locations with context
• "Generate status report for this week" → Compiled from JIRA, GitHub, with exports
• "The system is throwing a socket timeout error. What could be the cause?" → Gathers logs, inspects code, past issues for investigation

Search across Slack, GitHub, JIRA, code, and long-term memory with a single query. YADA:

• Searches long-term memory first (fast, no API calls)
• Falls back to live sources if needed
• Indexes results automatically (future queries are faster)
• Shows confidence levels so you know if info is fresh or cached

Understand relationships between systems:

• GitHub PR → find JIRA ticket → get Slack discussions
• Map usernames across systems (GitHub ≠ Slack ≠ JIRA)
• Timeline view of decisions across tools
• One query, complete picture

Recover institutional memory:

• "What did we decide about X last month?"
• "Who discussed this approach and why?"
• "When was this design decided?"
• Find discussions, decisions, and reasoning

Dig into code history:

• "When was this function introduced?"
• "What was the rationale for this implementation?"

Reduce information overload:

• Standup prep from JIRA tickets
• PR review with context from discussions
• Status reports from multiple sources
• Key decisions from scattered conversations

Persistent, searchable memory that:

• Improves over time (more queries = better future searches)
• Works offline (stored locally)
• Respects privacy (no vendor lock-in)
• Reduces API calls (memory hits are instant)

New to YADA? Start here:

1. Architecture & Design — How YADA works

   • Single-agent design with modular prompts
   • Memory-first strategy
   • Tool implementation patterns
   • Cross-integration intelligence

2. Tools Reference — Complete tool documentation

   • Slack tools (search, post, status, find user)
   • GitHub tools (issues, PRs, code search, activity)
   • JIRA tools (issues, search, activity)
   • Memory system (semantic search, indexing)
   • Filesystem tools (read/write with safety)
   • Code search & shell execution

3. Prompt System — How intelligence is implemented

   • Modular prompt composition
   • Core reasoning framework
   • Integration-specific knowledge
   • Design principles (reasoning frameworks, not rules)

• Natural language search over Slack messages (channels, DMs, threads)
• Filter by channel, user, date, etc. using Slack-style operators
• Fetch recent context from key channels or users
• (Optional later) Post messages or drafts back to Slack

• Search issues and PRs with natural language queries
• Get PR details: description, reviews, participants, linked issues
• Search code for symbols/patterns across a repo
• Inspect recent commits and activity by author

• Search JIRA issues using JQL or natural language
• Get issue details, activity, and history
• Track your assigned issues
• Monitor issue status and transitions

• Search code locally using ripgrep integration
• Find files by name or pattern
• Fast local code exploration

• Vector-based semantic memory using ChromaDB (or similar)
• Indexes Slack / GitHub snippets and local notes
• Cross-source recall: “What did we decide about X last month?”
• Stored under your home directory (no vendor lock-in)

• Read/write/append text files in a sandboxed workspace
• Export search results to Markdown/JSON/CSV
• Maintain running journals, notes, or scratchpads
• Safety model to avoid accidental overwrite or reading sensitive files

• Interactive REPL UI in your terminal
• Streaming responses
• Commands for help, history, clearing, exiting
• Usage metrics and performance tracking
• Slack user status checking
• Designed to be minimal, scriptable, and extensible

• Python 3.10+ (tested with 3.12)
• uv package manager
• OpenAI API key (with access to Agents SDK)
• Slack user token (required for Slack integration)
• GitHub Personal Access Token (optional, for GitHub integration)
• JIRA API token (optional, for JIRA integration)

Clone the repo and install dependencies:

git clone <repository-url>
cd yada

uv sync

This will create a virtual environment and install all Python dependencies defined in pyproject.toml.

YADA uses a YAML configuration file as the only configuration source. No environment variables or .env files are used.

By default, YADA looks for the config file at:

~/.yada/config.yaml

You can specify a different location using the --config option:

./yada.sh --config /path/to/config.yaml

1. Copy the template to your desired location:

   # For default location:
   cp config.yaml.template ~/.yada/config.yaml
   
   # Or use it in the project directory:
   cp config.yaml.template config.yaml
   ./yada.sh --config ./config.yaml

2. Edit the file with your API keys and settings

See config.yaml.template for all available options and their descriptions.

Required settings:

# Core API Keys (required)
openai_api_key: your-openai-api-key-here
slack_user_token: xoxp-your-slack-token-here

Optional integration settings:

# GitHub (optional)
github_token: ghp-your-github-token-here
github_repo: ""  # Auto-detected from git remote if empty

# JIRA (optional)
jira_server: https://your-domain.atlassian.net
jira_email: your-email@example.com
jira_api_token: your-jira-api-token-here
jira_project: YOUR_PROJECT_KEY

Application settings:

log_level: INFO  # DEBUG, INFO, WARNING, ERROR
cache_ttl: 300  # seconds
max_search_results: 20
slack_use_deep_links: false
console_trace: false  # Enable trace output to console
theme_mode: dark  # dark or light

# Model configuration
default_model: gpt-5
pdf_analysis_model: gpt-4o-mini
query_summarizer_model: gpt-5-nano

# Filesystem limits
filesystem_max_read_mb: 10
filesystem_max_write_mb: 50

GitHub token scopes:

• repo (or public_repo for public repos only)
• read:org (for searching org/private repos)

JIRA token:

• Generate at https://id.atlassian.com/manage-profile/security/api-tokens

From the project root, you can start YADA using either method:

Using the launcher script (recommended):

./yada.sh

Or directly with Python:

uv run python yada.py

You'll drop into the YADA REPL:

YADA > _

The yada.sh script supports several options:

./yada.sh                              # Use default config at ~/.yada/config.yaml
./yada.sh --config ./config.yaml       # Use config from project directory
./yada.sh --console-trace              # Show traces in console too
./yada.sh --log-level DEBUG            # Set log level to DEBUG
./yada.sh clean                        # Clean session database and cache

Available options:

• clean - Clean YADA session database and cache
• --config PATH - Path to config.yaml file (default: ~/.yada/config.yaml)
• --console-trace - Enable trace output to console (in addition to file)
• --log-level LEVEL - Set log level: DEBUG, INFO, WARNING, ERROR
• -h, --help - Show help message

Slack:

• What are the latest messages in #engineering?
• Search Slack for onboarding documents in #engineering last week
• What are the latest updates from @bob on the deployment issue?

GitHub:

• List open PRs related to authentication
• What has @alice worked on this week in GitHub?
• Has my last PR received any reviews? Summarize them.

JIRA:

• What are my assigned JIRA issues?
• Search JIRA for bugs related to authentication
• Show me the activity on JIRA-123

Code Search:

• Search the codebase for usages of the authenticate function
• Find all files named config.py

Cross-memory:

• What did we decide about the logging subsystem?
• Summarize all PRs related to "database migrations" from last month.

Filesystem:

• Save this summary as markdown in my workspace
• Append a short note to today's journal
• List files in my workspace exports directory
• Create a cheatsheet for our deployment process

YADA supports the following commands and shortcuts:

• /help - Show basic help
• /exit or /quit - Exit YADA
• /clear - Clear the screen
• Ctrl+C - Cancel the current request
• Ctrl+D - Exit YADA
• Multi-line input is supported via prompt-toolkit

yada/
├── agent/                   # Agent configuration and instructions
│   ├── agent.py             # Agent creation and configuration
│   └── tools_registry.py    # Tool registry mapping names to implementations
├── tools/                   # Integration tools
│   ├── base.py              # Base tool definitions
│   ├── slack.py             # Slack integration
│   ├── github.py            # GitHub integration
│   ├── jira.py              # JIRA integration
│   ├── memory.py            # Long-term memory interface
│   ├── filesystem.py        # Sandboxed filesystem operations
│   ├── search.py            # Code search and file finding
│   └── status.py            # Slack user status
├── memory/                  # Long-term memory system
│   ├── vector_memory.py     # Vector DB abstraction (ChromaDB)
│   └── indexer.py           # Snippet ingestion
├── ui/                      # User interface (REPL)
│   └── ui.py                # REPL loop and streaming
├── utils/                   # Utilities and helpers
│   ├── config.py            # Configuration management
│   ├── formatting.py        # Output formatting
│   ├── promptkit.py         # Prompt toolkit utilities
│   ├── performance.py       # Performance tracking
│   ├── metrics_storage.py   # Metrics database
│   ├── query_summarizer.py  # Query summarization
│   └── slack_user_cache.py  # Slack user caching
├── prompts/                 # Modular prompt templates
│   ├── core.txt             # Core system prompt
│   └── integrations/
│       ├── slack.txt
│       ├── github.txt
│       ├── jira.txt
│       ├── filesystem.txt
│       └── search.txt
├── docs/                    # Documentation, designs, implementation notes
├── test_scripts/            # Test and debug scripts
├── yada.py                  # Main entry point
├── yada.sh                  # Launcher script with options
├── config.yaml.template     # Configuration template
├── pyproject.toml           # Python dependencies and project metadata
├── CLAUDE.md                # Instructions for Claude Code
└── README.md

YADA is built around an agent + tools model using the OpenAI Agents SDK:

1. Agent Layer (agent/, prompts/)

   • agent/agent.py – Creates and configures the YADA agent using the OpenAI Agents SDK.
   • agent/tools_registry.py – Maps tool names (strings) to callable implementations for fast-path execution.
   • prompts/core.txt – Core system prompt with reasoning frameworks and policies.
   • prompts/integrations/ – Integration-specific prompt templates (Slack, GitHub, JIRA, filesystem, search).
   • Implements policies like "memory-first" retrieval and cross-source reasoning in prompts.

2. Tools Layer (tools/)

   All tools follow a production-grade pattern with explicit _impl functions (clean separation of business logic from SDK decoration):

   • slack.py – Slack Web API wrappers (search, user status, posting, user lookup).
   • github.py – GitHub REST/GraphQL wrappers (issues, PRs, code search, commits, activity).
   • jira.py – JIRA REST API wrappers (issue search, details, activity).
   • search.py – Local code search (ripgrep) and file finding.
   • memory.py – Interface to vector memory layer (store & retrieve).
   • filesystem.py – Sandboxed read/write/list/append operations.
   • status.py – Slack user status checking.
   • base.py – Base tool definitions and utilities.

3. Memory Layer (memory/)

   • vector_memory.py – Abstraction over ChromaDB vector database.
   • indexer.py – Routines to ingest and index Slack/GitHub snippets and local notes.

4. UI Layer (ui/, yada.py)

   • ui/ui.py – Interactive REPL using prompt-toolkit, streaming output, command parsing.
   • yada.py – Main entry point, configuration loading, agent initialization.
   • yada.sh – Launcher script with cleanup and debugging options.

5. Utils (utils/)

   • config.py – YAML config management (single source of truth).
   • formatting.py – Output formatting and rich text rendering.
   • promptkit.py – Prompt toolkit utilities for REPL.
   • performance.py – Performance tracking and timing.
   • metrics_storage.py – SQLite-based metrics database.
   • query_summarizer.py – LLM-based query summarization for metrics.
   • slack_user_cache.py – Efficient Slack user lookup caching.

Tool Implementation Pattern: All tools use explicit _impl functions that contain the business logic, separate from the OpenAI SDK decorators. This allows for easy testing and direct invocation from the tools registry.

Configuration: All settings are read from ~/.yada/config.yaml with hard-coded defaults as fallback. No environment variables or .env files are used.

Modular Prompts: System prompts are composed from a core template plus integration-specific templates, making it easy to add or remove integrations.

• Follow PEP 8 and SOLID principles - this is production code, not a prototype.
• Keep business logic in tools (using _impl functions); keep reasoning in prompts/.
• Use the tools registry pattern for all new tools to enable fast-path execution.
• Integration additions should include: tool implementation, prompt template, and registry entry.
• Treat YADA as a personal assistant: no org-specific assumptions in core code.
• All configuration is read from ~/.yada/config.yaml only - no environment variables or .env files.
• Use uv for all dependency management and running.
• See CLAUDE.md for detailed development guidelines and architectural principles.

TBD — choose whatever license matches your intended usage (personal, open-source, etc.).