Tired of explaining functionality to your non-techie colleagues?
You produce more code than ever but your docs are always outdated?
Let anyone ask how your product works — and get answers straight from the source code.
CodeAsk connects Claude to your GitHub repo via Serena code intelligence,
so it actually reads and understands your code before answering.
- Instant answers — ask plain-English questions, get responses grounded in your actual source code
- Slack-native — mention the bot in any channel and get answers where your team already works
- Always up-to-date — auto-syncs the repo on a configurable interval so answers reflect the latest code
- Database-aware — optionally connect a read-only database so the agent can combine code analysis with real data queries
- Extensible — plug in additional MCP tool servers alongside the built-in Serena code intelligence
┌──────────┐ ┌──────────┐
│ Slack @ │ │ HTTP API │
└────┬─────┘ └────┬─────┘
│ │
└─────────┬─────────┘
▼
┌─────────────────┐
│ Claude Agent │
│ (agentic loop) │
└────────┬────────┘
│ tool calls
┌───────┴───────┐
▼ ▼
┌─────────────────┐ ┌──────────────┐
│ Serena (MCP) │ │ Database MCP │
│ code intelligence│ │ (optional) │
└────────┬────────┘ └──────┬───────┘
│ reads code │ queries
▼ ▼
┌─────────────────┐ ┌──────────────┐
│ Your Repo │ │ Your DB │
│ (auto-synced) │ │ (read-only) │
└─────────────────┘ └──────────────┘
git clone https://github.com/matheins/codeask.git
cd codeask
pip install .
cp .env.example .env # ← fill in your keys
uvicorn src.main:app --port 8000Or use Docker
docker build -t codeask .
docker run --env-file .env -p 8000:8000 codeask| Variable | Required | Description |
|---|---|---|
ANTHROPIC_API_KEY |
Yes | Anthropic API key |
GITHUB_REPO_URL |
Yes | Git URL of the repo to explore |
API_KEY |
Yes | Secret key for HTTP endpoint auth (sent via X-API-Key header) |
GITHUB_TOKEN |
No | GitHub PAT for private repos |
REPO_BRANCH |
No | Branch to track (default: main) |
CLONE_DIR |
No | Local path to clone into (default: ./repo) |
SLACK_BOT_TOKEN |
No | Slack bot token (xoxb-...) |
SLACK_APP_TOKEN |
No | Slack app token (xapp-...) for Socket Mode |
SYNC_INTERVAL |
No | Seconds between repo syncs (default: 300) |
MCP_SERVERS_CONFIG |
No | Path to JSON config (or inline JSON) for additional MCP tool servers (Serena is built-in) |
CUSTOM_INSTRUCTIONS |
No | Extra context appended to the agent's system prompt (see Custom Instructions) |
MAX_ITERATIONS |
No | Max agent tool-call rounds (default: 20) |
ENABLE_THINKING |
No | Enable extended thinking for deeper reasoning (default: true) |
THINKING_BUDGET |
No | Token budget for thinking when enabled (default: 10000) |
DATABASE_URL |
No | SQLAlchemy connection URL for read-only DB access (see Database Integration) |
DB_MAX_ROWS |
No | Max rows returned per query (default: 100) |
DB_QUERY_TIMEOUT |
No | Query timeout in seconds (default: 30) |
curl http://localhost:8000/healthcurl -X POST http://localhost:8000/ask \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"question": "How does authentication work?"}'curl -X POST http://localhost:8000/sync \
-H "X-API-Key: YOUR_API_KEY"- Go to api.slack.com/apps and click Create New App → From scratch
- Give it a name (e.g. "CodeAsk") and select your workspace
- In the left sidebar, go to Socket Mode and toggle it on
- You'll be prompted to create an App-Level Token — give it a name (e.g. "codeask-socket") and add the
connections:writescope - Copy the token (starts with
xapp-...) → this is yourSLACK_APP_TOKEN
- Go to OAuth & Permissions in the left sidebar
- Under Bot Token Scopes, add:
app_mentions:read— lets the bot see when it's mentionedchat:write— lets the bot send messageschannels:history— lets the bot read thread context in public channelsgroups:history— lets the bot read thread context in private channels
- Go to OAuth & Permissions and click Install to Workspace
- Authorize the app
- Copy the Bot User OAuth Token (starts with
xoxb-...) → this is yourSLACK_BOT_TOKEN
- Go to Event Subscriptions in the left sidebar and toggle it on
- Under Subscribe to bot events, add
app_mention
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-tokenThe bot will start automatically when both tokens are present. Invite it to a channel and mention it to ask a question.
CodeAsk can optionally connect to a read-only database, allowing the agent to combine code analysis with real data queries. When enabled, the agent can answer questions like "how many users signed up this week?" by understanding the schema from code and querying the actual database.
Set DATABASE_URL in your .env file. Standard connection URLs work — no special format needed:
# PostgreSQL
DATABASE_URL=postgres://user:password@localhost:5432/mydb
# MySQL
DATABASE_URL=mysql://user:password@localhost:3306/mydb
# SQLite
DATABASE_URL=sqlite:///path/to/database.dbDrivers for PostgreSQL and MySQL are bundled — no extra install steps.
When DATABASE_URL is set, three tools are exposed to the agent:
| Tool | Description |
|---|---|
list_tables |
Lists all tables with row counts |
describe_table |
Shows columns, types, PKs, FKs, and indexes for a table |
run_query |
Executes a read-only SQL query (SELECT/WITH/EXPLAIN only) |
Database access is read-only with defense in depth:
- Read-only transactions — connections use
SET TRANSACTION READ ONLY(PostgreSQL/MySQL) to enforce read-only at the database level - SQL validation — queries are parsed and rejected if they contain write operations (
INSERT,UPDATE,DELETE,DROP,INTO, etc.) - Multi-statement rejection — only single SQL statements are allowed
- Row limits — results are capped at
DB_MAX_ROWS(default 100) - Query timeouts — dialect-specific statement timeouts prevent long-running queries
- PII protection — the agent is instructed to aggregate/anonymize data and never expose raw PII
Recommendation: For production deployments, create a dedicated read-only database user with
SELECT-only privileges. This provides the strongest guarantee regardless of application-level checks.
- The database server is optional — when
DATABASE_URLis not set, no database tools are exposed - Connection failure is non-fatal — the agent continues with code-only tools if the database is unavailable
- The agent automatically receives instructions for using database tools alongside code analysis when the database is connected
Use CUSTOM_INSTRUCTIONS to give the agent context about your product that isn't obvious from the code alone. This is especially useful when you have multiple MCP servers connected — the agent can use this context to pick the right tool for the job.
CUSTOM_INSTRUCTIONS="Our Organizations table has a stripeCustomerId column. When asked about billing or subscription questions, first query the database for the relevant org to get the Stripe ID, then use that ID with the Stripe MCP tools to look up invoices, subscriptions, or payment status."The text is appended to the agent's system prompt as-is, so write it the way you'd brief a new teammate.
Serena code intelligence is built-in — no configuration needed.
To give the agent access to additional tools, create a JSON config file and point MCP_SERVERS_CONFIG at it:
{
"mcpServers": {
"example": {
"command": "npx",
"args": ["-y", "@example/mcp-server"]
}
}
}Any server that speaks the Model Context Protocol will work. Only stdio transport is supported. Extra server failures are non-fatal — the agent continues with Serena and any other servers that connected successfully.
Use ${VAR} placeholders anywhere in the config to pull values from the host environment (e.g. your .env). This keeps secrets out of the config file so it's safe to commit:
{
"mcpServers": {
"signoz": {
"command": "/path/to/signoz-mcp-server",
"env": {
"SIGNOZ_URL": "${SIGNOZ_URL}",
"SIGNOZ_API_KEY": "${SIGNOZ_API_KEY}",
"LOG_LEVEL": "info"
}
}
}
}Substitution happens at startup before the subprocess is spawned. Unset variables are replaced with an empty string and a warning is logged.
Contributions are welcome! See CONTRIBUTING.md for guidelines.