How long does the integration take?

Change one base URL in an OpenAI-compatible client, or install the Python or TypeScript SDK; the quickstart routes a first request in a few minutes.

Will this lock us into another vendor?

No. The router is Apache-2.0 open source, your provider keys stay yours, and the API is OpenAI-compatible, so leaving is a change of base URL.

What happens when a provider fails?

The router falls back to the next model your policy allows and records the fallback in the trace, so an outage costs a retry, not an incident.

portu - Skill - OpenSmartRoute

Name: portu
Author: Chalet-Labs

Imported from Chalet-Labs/portu (AGENTS.md). Install upstream with npx skills add Chalet-Labs/portu. Copyright stays with the author.

Agent Instructions

Project

Portu is a native macOS SwiftUI crypto portfolio dashboard. It is local-first, has no backend, and has no telemetry. It aggregates holdings from Zapper, CoinGecko, and exchange APIs such as Kraken, Binance, and Coinbase.

Build And Run

This is a native macOS SwiftUI app generated by XcodeGen from project.yml.
Always regenerate Portu.xcodeproj after modifying project.yml.
Regenerate Portu.xcodeproj before building when project files may be stale. The repo run script already does this.
Prefer ./script/build_and_run.sh --verify to build, launch, and confirm the Portu process is running.
Use ./script/build_and_run.sh --logs or --telemetry when runtime logs are needed.
Use ./script/build_and_run.sh --debug to build, open LLDB, and start the app under the debugger.
Debug signing: read docs/agents/debug-signing.md before changing signing settings in project.yml or Configs/, or when macOS asks for keychain access after a rebuild.

Common commands:

just generate
just build
just release
just test-packages
just test
just lint
just lint-strict
just lint-fix
just format
just format-check
just clean

CI runs just format-check and just lint-strict. Plain just lint is not strict, so a local pass can still fail that gate.

XcodeBuildMCP

The repo declares XcodeBuildMCP in .mcp.json and enables the macos workflow in .xcodebuildmcp/config.yaml.
If native MCP tools are loaded, prefer the macOS workflow for build/test/discovery.
If native MCP tools are not loaded, use the CLI directly:

xcodebuildmcp macos build-and-run --project-path Portu.xcodeproj --scheme Portu --configuration Debug --derived-data-path .build/DerivedData --extra-args -skipMacroValidation
xcodebuildmcp macos test --project-path Portu.xcodeproj --scheme Portu --configuration Debug --derived-data-path .build/DerivedData --extra-args -skipMacroValidation

Architecture

Three SwiftPM packages have clean boundaries. Do not introduce cross-package imports that violate this layering:

PortuUI (views, theme, components)
  -> PortuCore (models, DTOs, keychain, protocols)

PortuNetwork (API clients, providers, price service)
  -> PortuCore

The app target in Sources/Portu/ imports all three packages and contains features, app state, and sync orchestration.

Swift And Concurrency

Swift 6.2 with strict concurrency (SWIFT_STRICT_CONCURRENCY: complete).
PortuUI uses defaultIsolation(MainActor.self).
The app target does not use default MainActor isolation because it is incompatible with TCA.
PortuNetwork providers are actor types and run off the main thread.
DTOs and enums must be plain Sendable for cross-isolation safety.
SwiftData @Model instances are read only on the actor that owns their ModelContext (the main actor for views, the @ModelActor for background fetchers).

Testing

Use Swift Testing (import Testing), not XCTest.
Use @Test, #expect(), #require(), and async test methods.
Use @Suite(.serialized) only when tests share mutable state. Do not add plain @Suite without traits.
Tests live in each package's Tests/ directory and in Tests/PortuTests/.
For behavior changes, run focused tests first, then the full Xcode scheme before calling the work complete.
When testing initializer default parameter behavior, call the initializer without those arguments instead of explicitly passing the default values.

Full Xcode scheme test command:

xcodebuild -project Portu.xcodeproj -scheme Portu -configuration Debug -derivedDataPath .build/DerivedData -skipMacroValidation test

TDD Rules

Never write implementation code without a failing test first.
Run tests after every change. Use XcodeBuildMCP when available.
Full cycle: RED (failing test), GREEN (minimal implementation), REFACTOR (clean up).
No implementation plans with code snippets. Tests are the spec.
When a test fails unexpectedly, diagnose before changing the test.
Run the full test suite before considering behavior complete.
Read specs from openspec/changes/ before generating tests.
Refactor only when tests are green. Do not refactor and change behavior simultaneously.

Code Style

Views: *View, *Sheet, *Sidebar, *Panel.
Types: *DTO, *Provider, *Service, *Error.
State: *State, *Status.
Enums use descriptive names, such as AccountKind, ExchangeType, and PositionType.
For composite lookup or deduplication keys, prefer a flat Hashable struct over nested dictionaries.
When passing URL-derived paths to FileManager APIs that take string paths, use url.path(percentEncoded: false).
When displayed percentages must sum to 100%, use largest-remainder rounding via ListShares.rounded(_:fractionDigits:) in PortuCore; never add the whole residual to one row.
For chart data built from grouped dictionaries or other unordered sources, use deterministic multi-key sorting, such as date then category.

SwiftData Models

Models use cascade delete rules and inverse relationships. When adding new models, follow the existing pattern in Packages/PortuCore/Sources/Models/.

Never use #Predicate with optional chaining through relationships, such as $0.position?.account?.isActive. CoreData generates unsupported TERNARY SQL and crashes at runtime. Use @Query without a filter and filter in Swift instead.

Avoid redundant SwiftData sort descriptors. If a query filters a field to a single value, do not add a secondary sort on that same field.
When deduplicating snapshot-like records, include every field needed for identity in the key, such as day, accountId, and assetId.

Formatting

SwiftFormat is used for code formatting and runs automatically via hooks on file edits. SwiftFormat 0.64.0 or later is required: .swiftformat sets --minversion 0.64.0, and CI pins 0.64.0 in .github/workflows/ci.yml.

Agent skills

Issue tracker

Issues are tracked in GitHub Issues for Chalet-Labs/portu. See docs/agents/issue-tracker.md.

Triage labels

Triage uses the five default canonical labels — see docs/agents/triage-labels.md for the mapping and which of them exist in this repo's tracker today.

Domain docs

Domain documentation uses a single-context layout. See docs/agents/domain.md.

Install portu and it becomes one more candidate the router can pick - when it fits.

A listing is a routing target with a manifest: what it does, which domains it covers, what it costs and who publishes it. Once installed it sits beside your own models and tools, is scored like any other candidate for each request, and shows up in the trace when it wins. Ratings come from workspaces that installed it, one per account.

{ "ocm": "1", "id": "chalet-labs-portu-portu", "kind": "skill", "name": "portu", "description": "Portu is a native macOS SwiftUI crypto portfolio dashboard. It is local-first, has no backend, and has no telemetry. It aggregates holdings from Zapper, CoinGecko, and exchange APIs such as Kraken, Binance, and Coinbase.", "publisher": "Chalet-Labs", "version": "1.0.0", "capabilities": { "domains": [ "coding", "finance" ], "tags": [ "skill-md", "github-agents" ], "languages": [ "en" ] }, "quality_prior": 0.6, "examples": [ "Portu is a native macOS SwiftUI crypto portfolio dashboard. It is local-first, has no backend, and has no telemetry. It aggregates holdings from Zapper, CoinGecko, and exchange APIs such as Kraken, Binance, and Coinbase." ], "primary": false, "metadata": { "source": { "provider": "github-agents", "repository": "https://github.com/Chalet-Labs/portu", "path": "AGENTS.md", "ref": "50e03292f2dd8c56669a6fa5f6a37d8730c5f299", "url": "https://github.com/Chalet-Labs/portu/blob/50e03292f2dd8c56669a6fa5f6a37d8730c5f299/AGENTS.md", "key": "Chalet-Labs/portu/AGENTS.md" } }, "instructions": "# Agent Instructions\n\n## Project\n\nPortu is a native macOS SwiftUI crypto portfolio dashboard. It is local-first, has no backend, and has no telemetry. It aggregates holdings from Zapper, CoinGecko, and exchange APIs such as Kraken, Binance, and Coinbase.\n\n## Build And Run\n\n- This is a native macOS SwiftUI app generated by XcodeGen from `project.yml`.\n- Always regenerate `Portu.xcodeproj` after modifying `project.yml`.\n- Regenerate `Portu.xcodeproj` before building when project files may be stale. The repo run script already does this.\n- Prefer `./script/build_and_run.sh --verify` to build, lau", "cost": { "context_tokens": 1595 } }

portu

About