Skip to content

Getting Started

ai-assist integrates with LLMs via the Anthropic Messages API, MCP (Model Context Protocol) servers, Agent Skills, and a temporal knowledge graph to provide intelligent monitoring, querying, and workflow automation.

Prerequisites

  • Python 3.14+
  • uv for dependency management
  • One authentication method (see below)

Install

Install uv if you don't have it:

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

Then install ai-assist:

git clone https://github.com/ai-assist-org/ai-assist
cd ai-assist
uv sync

Configure authentication

Copy the example environment file and fill in credentials for one of the methods below:

cp .env.example .env   # then edit .env

Enterprise / company Claude access via Google Cloud.

export ANTHROPIC_VERTEX_PROJECT_ID='your-gcp-project-id'
gcloud auth application-default login

Full walkthrough: see VERTEX_AI_SETUP.md in the repository.

Personal use with a free tier from Anthropic.

export ANTHROPIC_API_KEY='sk-ant-...'  # from console.anthropic.com

OpenRouter or a self-hosted, Anthropic-Messages-compatible endpoint. This takes precedence over the other methods.

# OpenRouter
export ANTHROPIC_BASE_URL='https://openrouter.ai/api'
export AI_ASSIST_API_KEY='sk-or-...'
export AI_ASSIST_MODEL='anthropic/claude-sonnet-4.6'

Configure identity

Set up your identity so the assistant knows who you are and adapts to your preferences:

uv run ai-assist /identity-init   # creates ~/.ai-assist/identity.yaml

Edit ~/.ai-assist/identity.yaml to configure your name, role, organization, and communication preferences:

version: '1.0'
user:
  name: 'Your Name'
  role: 'Your Role'
  organization: 'Your Company'
  context: |
    Describe your work context, team, and priorities here.
assistant:
  nickname: 'Nexus'
preferences:
  formality: 'professional'
  verbosity: 'concise'
  emoji_usage: 'moderate'

The user.context field is especially important — it is injected into the system prompt and gives the assistant awareness of your team, tools, and workflows.

Tip

Changes to identity.yaml are auto-reloaded — no restart needed.

📖 Full identity guide: Identity Configuration

Run

uv run ai-assist                      # interactive mode (default)
uv run ai-assist /monitor             # start monitoring mode
uv run ai-assist /query "..."         # one-off query
uv run ai-assist /run workflow.awl    # execute an AWL workflow

Next steps