`useActorProjects()` hook

useActorProjects() is the main project hook for the agents surface. It returns the current actor project list and the project-level mutations that create, update, archive, and unarchive those projects.

Usage

The following example shows a basic usage of useActorProjects().

import { useActorProjects } from '@wacht/nextjs';export default function ProjectsPage() {  const { projects, loading, createProject } = useActorProjects();  if (loading) {    return <div>Loading projects...</div>;  }  return (    <div>      <button        onClick={async () => {          await createProject({            name: 'Planning',            agent_id: 'agent_123',          });        }}      >        Create project      </button>      <ul>        {projects.map((project) => (          <li key={project.id}>{project.name}</li>        ))}      </ul>    </div>  );}

Return value

The hook returns the following fields and methods.

›

options?: { includeArchived?: boolean; enabled?: boolean } | undefined | undefined;

Optional list controls.

›

includeArchived?: boolean | undefined | undefined;

Include archived projects in the returned list.

›

enabled?: boolean | undefined | undefined;

Disable the query entirely when the surrounding session is not ready.

›

projects?: ActorProject[] | undefined;

Projects for the current actor.

›

id?: string | undefined;

Project identifier.

›

name?: string | undefined;

Project name.

›

description?: string | undefined | undefined;

Optional project description.

›

status?: string | undefined;

Current project status.

›

coordinator_thread_id?: string | undefined | undefined;

Coordinator thread for the project when present.

›

review_thread_id?: string | undefined | undefined;

Review thread for the project when present.

›

updated_at?: string | undefined;

Last update timestamp.

›

archived_at?: string | undefined | undefined;

Archive timestamp when the project has been archived.

›

createProject?: (request: CreateActorProjectRequest) => Promise<ApiResult<ActorProject>> | undefined;

Creates a new project. The created project is available on `result.data`.

›

updateProject?: (projectId: string, request: UpdateActorProjectRequest) => Promise<ApiResult<ActorProject>> | undefined;

Updates one project and returns the updated project on `result.data`.

›

archiveProject?: (projectId: string) => Promise<ApiResult<ActorProject>> | undefined;

Archives one project and returns the archived project on `result.data`.

›

unarchiveProject?: (projectId: string) => Promise<ApiResult<ActorProject>> | undefined;

Restores one archived project and returns the project on `result.data`.

Overview

This is the project list hook, not a route-selection hook. It fetches the actor project list, optionally includes archived projects, and revalidates the list after every project mutation.

When to use it

Use useActorProjects() anywhere you need the full project collection: project switchers, project overview screens, routed project shells, and project management dialogs.

If you need filtered or search-oriented project results for a command palette, use useActorProjectSearch() instead.

Examples

Resolve the current routed project

import { useMemo } from 'react';import { usePathname } from 'next/navigation';import { useActorProjects } from '@wacht/nextjs';export default function RoutedProjectShell() {  const pathname = usePathname();  const routeProjectId = useMemo(() => {    const match = pathname.match(/^\/agents\/p\/([^/]+)/);    return match?.[1] ?? null;  }, [pathname]);  const { projects } = useActorProjects();  const project = projects.find((item) => item.id === routeProjectId) ?? null;  return <div>{project?.name ?? 'No project selected'}</div>;}

useActorProjects() hook