Home

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• src/lib/constants.ts
• src/slack/views/app_home.ts
• src/slack/slack-events-handler.service.ts
• package.json
• agent-packages/packages/github/src/schema.ts
• src/llm/agent-evals/jira-agent/test-data.ts
• CONTRIBUTING.md

The "Home" feature refers to the Quix App Home tab within the Slack interface. It serves as the central administrative hub for configuring the Quix agent, managing integrations, and controlling user access within a Slack workspace. The view is dynamically rendered using Slack's Block Kit framework, providing a user-friendly interface for workspace administrators.

This page details the architecture, components, and data flow of the App Home feature, based on its implementation in the source code.

Sources: src/slack/views/app_home.ts, src/slack/slack-events-handler.service.ts

Event Handling Flow

The App Home view is triggered and updated based on user interactions within Slack. The process begins when a user navigates to the Quix app's Home tab.

1. A user opens the App Home tab in Slack.
2. Slack sends an app_home_opened event to the Quix backend.
3. The SlackEventsHandlerService receives this event and routes it to the AppHomeService.
4. The AppHomeService is responsible for constructing the appropriate view based on the user's permissions and the workspace's current configuration.
5. The constructed view, composed of Slack Block Kit elements, is then published back to the user's App Home tab.

The following diagram illustrates this event handling sequence.

This diagram shows the flow from a user opening the App Home tab to the view being rendered.

Sources: src/slack/slack-events-handler.service.ts:48-50

UI Components

The App Home view is composed of several dynamic components, each rendered based on the workspace's state and the user's authorization level.

Onboarding and Guidance

For workspaces where no integrations are configured, an onboarding view is displayed to guide new users. This component provides:

• Instructions for pinning the Quix app for easy access.
• Guidance on how to interact with the agent (e.g., via @Quix mentions or direct messages).
• A link to the Quix Slack community for support.

Sources: src/slack/views/app_home.ts:413-435, 457-469

OpenAI Key Configuration

Quix relies on an OpenAI API key for its AI capabilities. The App Home provides a view to manage this configuration.

• Key Not Set: If no key is configured, the view displays the status of the trial period, including the number of days remaining. A button prompts the user to "Add OpenAI Key".
• Key Set: If a key is already configured, a confirmation message is shown, along with an overflow menu allowing administrators to Edit or Remove the key.

Sources: src/slack/views/app_home.ts:285-325

Tool Connection Management

This is the primary component for managing integrations. A dropdown menu allows users to select a tool to configure. The dropdown is organized into three groups:

1. Connected Tools: Lists all integrations that are already configured for the workspace, including custom MCP servers.
2. Integrations: Lists all available, but not yet connected, standard integrations.
3. Add Your Own: An option to connect a custom MCP (Model Context Protocol) Server.

The list of connected tools is determined by partitioning the INTEGRATIONS constant based on whether a corresponding configuration relation exists on the SlackWorkspace model.

Sources: src/slack/views/app_home.ts:182-283

Integration Details View

When a tool is selected from the dropdown, this section updates to display its specific details and actions.

• If Connected: It shows connection details (e.g., Connected to https://my-jira.atlassian.net) and an overflow menu with options to Edit or Disconnect.
• If Not Connected: It displays help text (e.g., Connect JIRA to create, update, and view issues.) and a Connect button. For OAuth-based integrations, this button is a direct link to the installation URL.

The following diagram shows the logic for rendering the integration detail view.

This flow chart depicts how the UI adapts based on whether an integration is already configured.

Sources: src/slack/views/app_home.ts:327-411

Access Control

The App Home provides entry points for managing user permissions.

• Manage Access Controls: A button that opens a modal to configure which users or channels can interact with Quix.
• Manage Admins: A button to configure which team members have administrative privileges to manage Quix settings.

For non-admin users, a warning message is displayed, directing them to contact a workspace admin for access.

Sources: src/slack/views/app_home.ts:425-455

Supported Integrations

Quix supports a variety of business tools out-of-the-box. These integrations are defined in src/lib/constants.ts and packaged as individual modules within the agent-packages/ directory.

Name	Value	One-Line Summary	OAuth
JIRA	jira	Create, search, and update issues in JIRA	true
GitHub	github	Create, update, and search issues or PRs in GitHub	true
Hubspot	hubspot	Track contacts, companies, and deals in HubSpot	true
Zendesk	zendesk	Create, update, and view tickets in Zendesk	false
Postgres	postgres	Run natural-language queries on your Postgres database	false
Salesforce	salesforce	View and update opportunities, contacts, and accounts in Salesforce	true
Notion	notion	Search, browse, and retrieve content from your Notion workspace	false
Linear	linear	Manage and search tasks or issues in Linear	false
Okta	okta	Look up users, groups, and apps in Okta	false
JumpCloud	jumpcloud	Look up users, and groups in JumpCloud	false

Sources: src/lib/constants.ts:23-178, package.json:28-40

Agent Capabilities

Each integration exposes a set of "tools" that the AI agent can use to perform actions. The App Home can display the available functions for a selected tool by dynamically creating an instance of the corresponding agent tool export.

For example, the GitHub integration provides a rich set of tools for interacting with repositories, issues, and pull requests. The schemas for these tools are defined using zod.

Example: GitHub Agent Tools

Function Name	Description
searchIssuesOrPullRequests	Specify whether to search for issues or pull requests.
getGithubIssue	The number of the issue or PR to fetch.
createGithubIssue	The GitHub repository name where issue will be created.
addGithubAssignee	Repository where the issue or PR exists for assigning a user.
createPullRequest	Name of the repository where the PR will be created.
mergePullRequest	The pull request number to merge (e.g., 123).
searchRepositoryCode	The name of the GitHub repository to search in.

Sources: src/slack/views/app_home.ts:88-100, agent-packages/packages/github/src/schema.ts