⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
import type { FeedFilter, FeedOrder } from '@/lib/api/endpoints/activity';
import type { MentionSource } from '@/lib/api/endpoints/mentions';
const scimKey = (workspaceId: number | null) =>
workspaceId === null ? (['god', 'scim'] as const) : (['workspace', workspaceId, 'scim'] as const);
// Query keys shared by every service. Each is a stable tuple; a project/issue id
// or key scopes its entry. Kept in one registry so a mutation in one service can
// invalidate another service's queries by the same key.
export const qk = {
receivedInvites: ['receivedInvites'] as const,
receivedInvitesPage: (userId: string, email: string, params: unknown) =>
['receivedInvites', userId, email, params] as const,
externalRunTrace: (runId: number) => ['externalRunTrace', runId] as const,
runnerQueue: ['runnerQueue'] as const,
issueAgentRuns: (issueId: number) => ['issueAgentRuns', issueId] as const,
issueAgentRunTrace: (issueId: number, runId: number, traceId?: string) =>
['issueAgentRuns', issueId, 'trace', runId, traceId ?? null] as const,
internalRunTrace: (runId: number) => ['internalRunTrace', runId] as const,
projects: ['projects'] as const,
// Under projects, so what refreshes the project list refreshes every search with it.
projectSearch: (filters: unknown) => ['projects', 'search', filters] as const,
teams: ['teams'] as const,
// One team: its counters and what the caller may do with what it holds.
team: (teamId: number) => ['team', teamId] as const,
workspaces: ['workspaces'] as const,
// One workspace a caller manages. Its managers, candidates and settings sit under it, so
// invalidating the workspace refreshes all of them.
workspace: (workspaceId: number) => ['workspace', workspaceId] as const,
workspaceManagers: (workspaceId: number) => ['workspace', workspaceId, 'managers'] as const,
workspaceManagerCandidates: (workspaceId: number, search: string) =>
['workspace', workspaceId, 'managers', 'candidates', search] as const,
scim: scimKey,
scimGroups: (workspaceId: number | null) => [...scimKey(workspaceId), 'groups'] as const,
scimProjects: (workspaceId: number | null) => [...scimKey(workspaceId), 'projects'] as const,
teamProjectDefaults: (teamId: number) => ['team', teamId, 'project-defaults'] as const,
// The project templates of a workspace and those its teams see share one root, since
// saving or deleting one changes the lists of every team.
projectTemplates: ['project-templates'] as const,
teamProjectTemplates: (teamId: number) => ['project-templates', 'team', teamId] as const,
teamProjectTemplate: (teamId: number, templateId: number) =>
['project-templates', 'team', teamId, templateId] as const,
workspaceProjectTemplates: (workspaceId: number) =>
['project-templates', 'workspace', workspaceId] as const,
workspaceProjectTemplate: (workspaceId: number, templateId: number) =>
['project-templates', 'workspace', workspaceId, templateId] as const,
importedTemplatePreview: (workspaceId: number, template: unknown) =>
['project-templates', 'workspace', workspaceId, 'import', template] as const,
projectTemplatePreview: (workspaceId: number, projectId: number, include: unknown) =>
['project-templates', 'workspace', workspaceId, 'preview', projectId, include] as const,
templatePublisher: (workspaceId: number) => ['template-publisher', workspaceId] as const,
// The members of a team and the projects it owns, each read by its own section. A
// page is scoped by the search term and the window it was read with.
teamMembers: (teamId: number, params: unknown) => ['team', teamId, 'members', params] as const,
teamProjects: (teamId: number, params: unknown) => ['team', teamId, 'projects', params] as const,
// Every project of the team, for the pickers and the MCP switches that act on all
// of them.
teamProjectOptions: (teamId: number) => ['team', teamId, 'projects', 'options'] as const,
// Every page of a team's projects and its options list, for a write that changes
// what they show.
anyTeamProjects: (teamId: number) => ['team', teamId, 'projects'] as const,
// One project the team owns, loaded when its row is opened, and one page of its
// members (the search term and the window scope the entry).
teamProject: (teamId: number, projectId: number) =>
['team', teamId, 'project', projectId] as const,
teamProjectMembers: (teamId: number, projectId: number, params: unknown) =>
['team', teamId, 'project', projectId, 'members', params] as const,
// Every team detail and every project of one, for a write that changes what any
// of them shows (a project gained or lost a member).
anyTeam: ['team'] as const,
// A team's notification provider credentials.
notificationSettings: (teamId: number) => ['notificationSettings', teamId] as const,
// The board scaffold (columns/types/labels/fields/viewer) for a project.
project: (projectKey: string) => ['workItems', projectKey] as const,
// Every project scaffold, for a write outside the project that changes what one
// of them shows (a team setting the project inherits).
anyProject: ['workItems'] as const,
// The board's issues, their relations and the change marker for a project.
// Split from the scaffold so issue writes and live-refresh touch only the
// issues, not the scaffold.
boardIssues: (projectKey: string) => ['boardIssues', projectKey] as const,
// A project's archived issues.
archivedIssues: (projectKey: string) => ['archivedIssues', projectKey] as const,
// Command-palette issue search, scoped to a project and the search term.
issueSearch: (projectKey: string, q: string) => ['issueSearch', projectKey, q] as const,
issueSearchAll: (q: string, excludeProjectId: number | null) =>
['issueSearchAll', q, excludeProjectId] as const,
// The project's auto-archive thresholds and subtask automations (the
// Configuration settings section).
autoArchive: (projectKey: string) => ['autoArchive', projectKey] as const,
subtaskAutomation: (projectKey: string) => ['subtaskAutomation', projectKey] as const,
// The project's repository integration settings (the Repositories settings section).
gitSettings: (projectKey: string) => ['gitSettings', projectKey] as const,
gitConnections: (projectKey: string) => ['gitConnections', projectKey] as const,
gitAvailableRepositories: (projectKey: string, connectionId: number, search: string) =>
['gitConnections', projectKey, connectionId, 'repositories', search] as const,
// The member's own notification preferences for a project.
notificationPreferences: (projectKey: string) => ['notificationPreferences', projectKey] as const,
views: (projectKey: string) => ['views', projectKey] as const,
actions: (projectKey: string) => ['actions', projectKey] as const,
webhooks: (projectKey: string) => ['webhooks', projectKey] as const,
webhookDeliveries: (webhookId: number) => ['webhookDeliveries', webhookId] as const,
// The project's import jobs (the Import/Export settings section).
importJobs: (projectKey: string) => ['importJobs', projectKey] as const,
// The mapping review preview for one candidate Plane project, before a job exists.
planePreview: (projectKey: string, planeProjectId: string) =>
['planePreview', projectKey, planeProjectId] as const,
// The same preview for one Linear team's workflow states.
linearPreview: (projectKey: string, teamId: string) =>
['linearPreview', projectKey, teamId] as const,
// The same preview for one Trello board's lists and members.
trelloPreview: (projectKey: string, boardId: string) =>
['trelloPreview', projectKey, boardId] as const,
// Saved dashboards (the analytics tabs) and the read-only metrics behind their
// widgets. `kind` names the metric (stats/pulse/throughput/breakdown/...) and
// `params` scopes it to the widget's query (window, filters).
dashboards: (projectKey: string) => ['dashboards', projectKey] as const,
documents: (projectKey: string, q = '', archived = false) =>
['documents', projectKey, 'list', archived ? 'archived' : 'active', q] as const,
documentListsForProject: (projectKey: string) => ['documents', projectKey, 'list'] as const,
document: (projectKey: string, documentId: number) =>
['documents', projectKey, 'document', documentId] as const,
documentRevisions: (projectKey: string, documentId: number) =>
['documents', projectKey, 'document', documentId, 'revisions'] as const,
documentComments: (projectKey: string, documentId: number) =>
['documents', projectKey, 'document', documentId, 'comments'] as const,
documentAssets: (projectKey: string, documentId: number) =>
['documents', projectKey, 'document', documentId, 'assets'] as const,
documentIssueLinks: (projectKey: string, documentId: number) =>
['documents', projectKey, 'document', documentId, 'issues'] as const,
// Who the "@" menu offers where a mention is written. A document's sits under the
// document, so what refreshes the document refreshes it too.
mentionCandidates: (source: MentionSource) =>
source.on === 'document'
? ([
'documents',
source.projectKey,
'document',
source.documentId,
'mentions',
source.place,
] as const)
: (['mentionCandidates', source.projectKey, source.place] as const),
issueDocumentLinks: (projectKey: string, issueId: number) =>
['documents', projectKey, 'issue', issueId] as const,
initiativeDocumentLinks: (projectKey: string, initiativeId: number) =>
['documents', projectKey, 'initiative', initiativeId] as const,
// Note boards (the notes canvases). `noteBoardsForProject` is the invalidation
// base for every list/search variant; `noteBoardsSearch` is one paged switcher
// query (scoped by search text); `noteBoard` is a single board with its canvas.
noteBoardsForProject: (projectKey: string) => ['noteBoards', projectKey] as const,
noteBoardsSearch: (projectKey: string, q: string) =>
['noteBoards', projectKey, 'search', q] as const,
noteBoard: (projectKey: string, boardId: number) =>
['noteBoards', projectKey, 'board', boardId] as const,
noteBoardAccessCandidates: (projectKey: string) =>
['noteBoards', projectKey, 'accessCandidates'] as const,
agentAnalytics: (teamId: number, days: number, projectId: number | null) =>
['agentAnalytics', teamId, days, projectId] as const,
workspaceAgentAnalytics: (workspaceId: number, days: number) =>
['workspaceAgentAnalytics', workspaceId, days] as const,
// The model prices of a workspace: the models it uses, and pages of the built-in table.
modelPrices: (workspaceId: number) => ['modelPrices', workspaceId] as const,
usedModelPrices: (workspaceId: number) => ['modelPrices', workspaceId, 'used'] as const,
modelPriceCatalog: (workspaceId: number, params: unknown) =>
['modelPrices', workspaceId, 'catalog', params] as const,
analytics: (projectKey: string, kind: string, params?: unknown) =>
['analytics', projectKey, kind, params ?? {}] as const,
analyticsForProject: (projectKey: string) => ['analytics', projectKey] as const,
// Project membership and invite links (the Members section).
members: (projectKey: string) => ['members', projectKey] as const,
// One page of them. Under the key above, so a membership write invalidates every
// page with the one call.
memberPage: (projectKey: string, params: unknown) =>
['members', projectKey, 'page', params] as const,
// Every project's member list, for a write that changes what any of them resolves
// to (a role edited on the team they belong to).
anyMembers: ['members'] as const,
invites: (projectKey: string) => ['invites', projectKey] as const,
anyInvites: ['invites'] as const,
// Who a project can be filled from: the members of its team who are not in it yet.
memberCandidates: (projectKey: string) => ['members', projectKey, 'candidates'] as const,
// The invites of a team, including the ones into its projects.
teamInvites: (teamId: number) => ['teamInvites', teamId] as const,
anyTeamInvites: ['teamInvites'] as const,
inviteCandidates: (teamId: number, search: string) =>
['teamInvites', teamId, 'candidates', search] as const,
inviteSearch: ['inviteSearch'] as const,
// The roles a team offers, which is what every project of it assigns from. The
// permission catalog is app-static, so it is scoped to no team.
teamRoles: (teamId: number, params: unknown) => ['teamRoles', teamId, params] as const,
teamRoleOptions: (teamId: number) => ['teamRoles', teamId, 'options'] as const,
anyTeamRoles: (teamId: number) => ['teamRoles', teamId] as const,
roleUsage: (teamId: number, roleId: number) => ['roleUsage', teamId, roleId] as const,
anyRoleUsage: ['roleUsage'] as const,
permissionCatalog: ['permissionCatalog'] as const,
// A team's AI agents (its Agents section), and the ones working in one of its
// projects (the project's read-only list). The action catalog is team-scoped on the
// API, so it hangs off the same key with a 'tools' tail.
aiAgents: (teamId: number, projectId?: number) =>
['aiAgents', teamId, projectId ?? 'all'] as const,
agentDirectory: (teamId: number, projectId: number) =>
['aiAgents', teamId, projectId, 'directory'] as const,
anyAiAgents: ['aiAgents'] as const,
teamAiAgents: (teamId: number) => ['aiAgents', teamId] as const,
agentTools: (teamId: number) => ['aiAgents', teamId, 'tools'] as const,
// The skills enabled on one agent (the agent editor's Skills tab).
agentSkillLinks: (teamId: number, agentId: number) =>
['aiAgents', teamId, agentId, 'skills'] as const,
// An agent's triggered run history (the runs sidebar).
agentRuns: (teamId: number, agentId: number) => ['aiAgents', teamId, agentId, 'runs'] as const,
invocationSecret: (teamId: number, agentId: number) =>
['aiAgents', teamId, agentId, 'invocationSecret'] as const,
agentSchedules: (projectKey: string) => ['agentSchedules', projectKey] as const,
// One page of them: the window scopes the entry.
agentSchedulePage: (projectKey: string, params: unknown) =>
['agentSchedules', projectKey, 'page', params] as const,
agentScheduleRuns: (projectKey: string, scheduleId: number) =>
['agentSchedules', projectKey, scheduleId, 'runs'] as const,
// The caller's chat threads with one agent (the AI Chat history rail) and the
// transcript of one thread (restored when a thread is opened). A search is a list of
// its own, so the unsearched list stays cached while one is typed.
agentThreadLists: (projectKey: string, agentId: number) =>
['aiAgents', projectKey, agentId, 'threadList'] as const,
agentThreads: (projectKey: string, agentId: number, q = '') =>
['aiAgents', projectKey, agentId, 'threadList', q] as const,
// The conversations starred with one agent: the group on top of the history, and what
// the star in the tabs bar reads its state from.
agentFavoriteThreads: (projectKey: string, agentId: number) =>
['aiAgents', projectKey, agentId, 'favoriteThreads'] as const,
agentThreadMessages: (projectKey: string, agentId: number, threadId: string) =>
['aiAgents', projectKey, agentId, 'threads', threadId] as const,
// Everything integration-scoped. A credential belongs to the team, so changing one
// is invalidated at this prefix: the pickers its projects fill from go stale too.
integrations: ['integrations'] as const,
// One page of the team's stored credentials (its Integrations tab); the window
// scopes the entry. The integration catalog and an LLM provider's models sit beside
// it, under the same team prefix.
teamCredentialPage: (teamId: number, params: unknown) =>
['integrations', 'team', teamId, 'page', params] as const,
integrationCatalog: (teamId: number) => ['integrations', 'team', teamId, 'catalog'] as const,
integrationModels: (teamId: number, provider: string) =>
['integrations', 'team', teamId, 'models', provider] as const,
// The connected integrations as picker options, under the same prefix so a
// credential mutation refreshes them too.
integrationOptions: (teamId: number, kind?: string) =>
['integrations', 'team', teamId, 'options', kind ?? 'all'] as const,
// Everything skill-scoped in one team. A write invalidates at this prefix, so the
// page the section shows, the whole library the picker reads and the skill the
// editor has open all refresh together.
agentSkills: (teamId: number) => ['agentSkills', teamId] as const,
agentSkillPage: (teamId: number, params: unknown) =>
['agentSkills', teamId, 'page', params] as const,
agentSkillOptions: (teamId: number) => ['agentSkills', teamId, 'options'] as const,
agentSkill: (teamId: number, skillId: number) =>
['agentSkills', teamId, 'skill', skillId] as const,
// The team's configured tools (its Tools section) and the tools enabled on one agent
// (the agent editor's Tools section).
configuredTools: (teamId: number) => ['configuredTools', teamId] as const,
configuredToolPage: (teamId: number, params: unknown) =>
['configuredTools', teamId, 'page', params] as const,
configuredToolOptions: (teamId: number) => ['configuredTools', teamId, 'options'] as const,
agentToolLinks: (teamId: number, agentId: number) =>
['aiAgents', teamId, agentId, 'tool-configs'] as const,
issue: (id: number) => ['issue', id] as const,
issueDevelopmentRepositories: (id: number) =>
['issue', id, 'development', 'repositories'] as const,
issueDevelopmentPullRequests: (id: number, repositoryId: number, state: 'open' | 'all') =>
['issue', id, 'development', 'repositories', repositoryId, 'pullRequests', state] as const,
issueDevelopmentBranches: (id: number, repositoryId: number) =>
['issue', id, 'development', 'repositories', repositoryId, 'branches'] as const,
// Under the issue prefix, so every issue mutation refreshes the cycles with it.
issueCycles: (id: number) => ['issue', id, 'cycles'] as const,
anyIssue: ['issue'] as const,
// Resolving an issue by its project-scoped number (the identifier-based URL).
issueBySeq: (projectKey: string, seq: number) => ['issueBySeq', projectKey, seq] as const,
// Every read of one issue's feed sits under this key, so invalidating it refreshes
// them all.
feed: (id: number) => ['feed', id] as const,
flatFeed: (id: number, filter: FeedFilter | null, order: FeedOrder) =>
['feed', id, 'flat', filter, order] as const,
// The same feed split by status, paged on its own.
groupedFeed: (id: number, filter: FeedFilter | null, order: FeedOrder) =>
['feed', id, 'grouped', filter, order] as const,
feedCounts: (id: number) => ['feed', id, 'counts'] as const,
// The status stretches of the timeline view, and the entries of one stretch read
// when it is opened. Both keyed under the feed, so every existing feed
// invalidation refreshes them too.
timeline: (id: number) => ['feed', id, 'timeline'] as const,
timelineItems: (id: number, from: string, to: string | null) =>
['feed', id, 'timelineItems', from, to] as const,
// Initiatives: a project's list (params narrow, sort and page it), the per-status
// tab counts, one initiative, and one initiative's activity feed.
initiatives: (projectKey: string, params: unknown) =>
['initiatives', projectKey, params] as const,
initiativesForProject: (projectKey: string) => ['initiatives', projectKey] as const,
// The linkable initiatives behind the issue picker, narrowed by the typed search.
initiativeOptions: (projectKey: string, params: Record<string, unknown>) =>
['initiatives', projectKey, 'options', params] as const,
initiativeCounts: (projectKey: string) => ['initiativeCounts', projectKey] as const,
initiative: (id: number) => ['initiative', id] as const,
initiativeFeed: (id: number) => ['initiativeFeed', id] as const,
// Prefix keys: issue mutations invalidate every initiative query without
// knowing the id (see invalidateInitiatives in issues.service).
anyInitiative: ['initiative'] as const,
anyInitiativeFeed: ['initiativeFeed'] as const,
anyInitiatives: ['initiatives'] as const,
// Cycles: a project's list and one cycle. Issue mutations invalidate the whole
// 'cycles' subtree, since planning an issue moves a cycle's progress. The list the
// page reads is split in two — what is still planned, and the paged archive —
// under the same prefix, so one invalidation covers all three.
cycles: (projectKey: string) => ['cycles', projectKey] as const,
plannedCycles: (projectKey: string) => ['cycles', projectKey, 'planned'] as const,
cycleOptions: (projectKey: string) => ['cycles', projectKey, 'options'] as const,
completedCycles: (projectKey: string) => ['cycles', projectKey, 'completed'] as const,
cycle: (id: number) => ['cycle', id] as const,
anyCycles: ['cycles'] as const,
anyCycle: ['cycle'] as const,
attachments: (id: number) => ['attachments', id] as const,
initiativeAttachments: (id: number) => ['initiativeAttachments', id] as const,
// The time entries of one issue. Their sum comes with the issue, so a write
// refreshes that read too.
worklogs: (id: number) => ['worklogs', id] as const,
// A project's inbox notifications (the list, scoped by the active filters) and the
// project's unread count (the sidebar badge + live-refresh target).
notifications: (projectKey: string, filters?: unknown) =>
['notifications', projectKey, filters ?? {}] as const,
notificationsUnread: (projectKey: string) => ['notificationsUnread', projectKey] as const,
// The unread count across every project (the app icon badge).
notificationsUnreadTotal: ['notificationsUnreadTotal'] as const,
// The signed-in user's WebAuthn passkeys (account security page).
passkeys: ['passkeys'] as const,
// The OAuth applications the signed-in user authorized (account security page).
connectedApps: ['connectedApps'] as const,
// The signed-in user's connected external accounts (accounts page): the linked
// Telegram account, and the auth providers better-auth reports.
telegramAccount: ['telegramAccount'] as const,
linkedAccounts: ['linkedAccounts'] as const,
// The instance sign-in policy, including which social providers are configured.
authConfig: ['authConfig'] as const,
// The name an MCP client registered with, shown on the OAuth consent page.
oauthClientName: (clientId: string) => ['oauthClientName', clientId] as const,
// The signed-in user's personal API keys (API keys page).
apiKeys: ['apiKeys'] as const,
// The signed-in user's interface preferences (timezone, theme, issue open mode,
// start page). Read app-wide, not just on the preferences page.
accountPreferences: ['accountPreferences'] as const,
// Instance administration (god mode): the sign-in policy, the mail provider, the
// sign-in providers (Google and OIDC) and the Telegram bot. Not scoped to a project.
instanceAuthSettings: ['instanceAuthSettings'] as const,
instanceEmailSettings: ['instanceEmailSettings'] as const,
instanceGoogleSettings: ['instanceGoogleSettings'] as const,
instanceOidcSettings: ['instanceOidcSettings'] as const,
instanceTelegramSettings: ['instanceTelegramSettings'] as const,
instanceProjectDefaults: ['instanceProjectDefaults'] as const,
instanceAgentSettings: ['instanceAgentSettings'] as const,
instanceSharingSettings: ['instanceSharingSettings'] as const,
instanceEmbedSites: ['instanceEmbedSites'] as const,
instanceEmailTemplates: ['instanceEmailTemplates'] as const,
instanceEmailPreview: (draft: unknown) => ['instanceEmailPreview', draft] as const,
instanceStorageSettings: ['instanceStorageSettings'] as const,
systemRoles: ['systemRoles'] as const,
// The upload limits as read by the upload UI (open to any signed-in user).
storageSettings: ['storageSettings'] as const,
// The running version (any signed-in user) and the upstream release check (god).
appVersion: ['appVersion'] as const,
// The post-upgrade screen: the running release's notes, the backup and the
// migration report.
whatsNew: ['whatsNew'] as const,
updateStatus: ['updateStatus'] as const,
// The bindings every client resolves from, and the god-mode editor's copy.
hotkeySettings: ['hotkeySettings'] as const,
instanceHotkeySettings: ['hotkeySettings', 'god'] as const,
// The instance user directory: the list (scoped by the active filters) and one
// account with its project access.
instanceUsers: (filters: unknown) => ['instanceUsers', filters] as const,
instanceUser: (userId: string) => ['instanceUser', userId] as const,
anyInstanceUsers: ['instanceUsers'] as const,
// The instance project directory: the list (scoped by the active filters) and one
// project with its members.
instanceProjects: (filters: unknown) => ['instanceProjects', filters] as const,
instanceProject: (projectId: number) => ['instanceProject', projectId] as const,
// The instance team directory: the list (scoped by the active filters) and one team
// with its projects and members.
instanceTeams: (filters: unknown) => ['instanceTeams', filters] as const,
instanceTeam: (teamId: number) => ['instanceTeam', teamId] as const,
instanceTeamProjects: (teamId: number, filters: unknown) =>
['instanceTeamProjects', teamId, filters] as const,
instanceTeamMembers: (teamId: number, filters: unknown) =>
['instanceTeamMembers', teamId, filters] as const,
};