@amaster.ai/pi-teamwork

Pi extension for team collaboration and project management. Provides LLM-callable tools to interact with issue trackers and project management systems.

Supported Providers

• Multica — CLI-based adapter via multica

Configuration

Auto-Install

Runtime auto-installation is disabled because mutable package-manager taps and download scripts cannot provide the pinned artifact verification required in a credential-bearing agent process. Install a pinned Multica release separately and put the verified binary on $PATH, or configure multica.binary.

The deprecated autoInstall: true setting no longer executes an installer. It only reports a clear error when the binary is missing.

Configuration may live in user/agent settings or in a trusted project's .pi/settings.json. Project settings are ignored when trust is declined and do not expand ${ENV_VAR}; keep environment-backed credentials in user or agent settings.

Mode 1 — Self-hosted server

For teams running their own Multica server. The extension runs multica setup self-host with the provided URLs, then authenticates with the token:

{
  "pi-teamwork": {
    "enabled": true,
    "provider": "multica",
    "multica": {
      "serverUrl": "https://api.your-server.com",
      "appUrl": "https://your-server.com",
      "token": "<token-from-multica-server>"
    }
  }
}

Mode 2 — Pre-configured environment

Run multica setup once on the machine and finish login through multica's normal flow. The extension will reuse that state:

{
  "pi-teamwork": {
    "enabled": true,
    "provider": "multica",
    "multica": {
      "workspace": ""
    }
  }
}

Mode 3 — Headless token (Multica Cloud)

For CI or non-interactive environments where you can't run multica setup. The extension will run multica login --token <token> on every session_start:

{
  "pi-teamwork": {
    "enabled": true,
    "provider": "multica",
    "multica": {
      "token": "<token-from-multica-server>"
    }
  }
}

⚠️ token is a credential. Keep it out of version control — put it in a local-only settings file or inject via env-substituted config.

Tools

Commands

• /teamwork-status — Show current provider status

Architecture

src/
├── index.ts              # Generic tool layer (provider-agnostic)
├── types.ts              # TeamworkProvider interface + shared types
└── adapters/
    └── multica.ts        # Multica CLI adapter + initialization

The extension uses a provider pattern — index.ts registers tools that delegate to a TeamworkProvider interface. Adding a new provider (Linear, Jira, etc.) only requires implementing the interface and adding a factory branch in session_start.

Structured results (Pi 0.99+)

Teamwork tools declare outputSchema: workspace_list/issue_list/project_list return { workspaces | issues | projects, total, truncated }; issue_get/create/update return { issue, truncated }; issue_comment returns { comment, truncated }. Issue objects retain their existing IDs/statuses and public fields; arbitrary provider metadata is excluded. teamwork_status exposes the provider and available running/pid/status fields, excluding raw CLI output. Failures return { error, truncated } with isError: true, without CLI diagnostics or credentials. Tracker writes still require user authorization.

const result = await tools.issue_list({ status: "todo" });
if (result.error) throw new Error(result.error);
text(result.issues.map(issue => ({ id: issue.id, title: issue.title, status: issue.status })));
// Once the user has authorized this issue's status update:
// await tools.issue_update({ id: result.issues[0].id, status: "in_progress" });

Structured output is limited to 12 KiB and top-level lists to 100 complete records. truncated: true indicates omitted records; total retains the original count where available. Oversized records with an id retain that complete ID and small scalar metadata, omit large fields, and carry truncated: true both on the record and envelope; callers must check that flag before reusing content for an update. Oversized results without a record ID return a typed output-limit error instead of clipped paths or content. A write may already have completed when that happens: inspect saved state before retrying. Readable text and renderer details are independently bounded.

Multica initialization runs in the background with one 10-second budget across CLI checks, setup, daemon startup, and login. Ordinary prompts do not wait for it; teamwork tools wait for initialization. Each later tool or status-command invocation has one 30-second deadline covering initialization waits and all CLI steps. Caller cancellation reaches the running CLI and prevents subsequent commands (including the remaining update/get steps); session shutdown cancels outstanding CLI work.

Failure diagnostics

Configuration and login failures stop initialization and remain visible to waiting tools with a safe error category. A failed daemon start is accepted only after a status check confirms that the daemon is running. A version-probe timeout is not treated as evidence that the CLI needs installation.