Timex

Deck-styled native scheduler for project-scoped, time-boxed work, exposed to coding agents over MCP.

Layout

• app/ is the Native SDK app package. It contains the UI, model, assets, and Native manifest.
• mcp/ is the standalone Zig package for SQLite storage, timex-mcp, and the timex-store helper CLI.
• The root build.zig only orchestrates both packages. It does not import or require a checked-in Native SDK dependency.

Features

• Create and select projects.
• Create timers with a required duration, optional details, and an optional RFC 3339 calendar start.
• Start, pause, reset, and delete timers; running timers count down and continue into overdue time.
• Automatically start the oldest due timer while the Native app is open, while preserving schedule drift when another timer is active.
• Deliver one-time macOS notifications for due scheduled work while Timex is open.
• Persist projects and timers in SQLite.
• Run timex-mcp as a stdio MCP server for agent control.
• Let the Native app talk to storage through timex-store, so SQLite is isolated from the app binary.

Build

zig build          # builds timex-mcp, timex-store, and the Native app
zig build mcp      # builds only the standalone MCP/store binaries
zig build app      # builds only the Native app via `native build app`
zig build run      # runs the Native app with the MCP server sidecar
zig build test     # runs MCP/store tests and Native app tests

The root MCP binaries install to zig-out/bin/timex-mcp and zig-out/bin/timex-store. Native app artifacts are produced by the Native CLI under app/zig-out/.

Runtime

• Set TIMEX_DB_PATH=/path/to/timex.sqlite to use a specific SQLite database.
• Set TIMEX_STORE_BIN=/path/to/timex-store when launching the app from a working directory where zig-out/bin/timex-store is not available.
• MCP clients should launch zig-out/bin/timex-mcp.

Use Timex with a coding agent

Timex is a local stdio MCP server. Build it before starting an agent:

zig build mcp

The repository includes a project-local Codex configuration at .codex/config.toml:

[mcp_servers.timex]
command = "zig-out/bin/timex-mcp"
startup_timeout_sec = 10
tool_timeout_sec = 30

Start Codex from the repository root so the relative command resolves to the freshly built binary:

codex

Codex starts the MCP server when the session opens. After rebuilding timex-mcp, restart Codex so the session uses the new binary; an already-running MCP process does not hot-reload.

You can verify the server from Codex with a prompt such as:

Use Timex to create a project named Codex test, create a 25-minute timer named MCP smoke test in it, start the timer, and report the resulting IDs and state.

For a disposable test database, set TIMEX_DB_PATH before launching Codex:

TIMEX_DB_PATH=/tmp/timex-codex-test.sqlite codex

If Timex tools do not appear, confirm that zig-out/bin/timex-mcp exists and that Codex was started from this repository root so .codex/config.toml and its relative command are resolved. If the tools appear but calls fail after a rebuild, restart Codex before debugging the installation—the current session may still be connected to the previous server process.

To add Timex to another coding agent, use its stdio MCP configuration and point command at the built binary. The command must run with the repository root as its working directory, or use an absolute path:

{
  "mcpServers": {
    "timex": {
      "command": "/absolute/path/to/timex/zig-out/bin/timex-mcp",
      "env": {
        "TIMEX_DB_PATH": "/absolute/path/to/timex.sqlite"
      }
    }
  }
}

Use the equivalent mcpServers.timex entry for agents whose configuration is TOML or YAML. Keep the server on stdio; it does not expose an HTTP endpoint. The available tools and resources are documented in skills/timex-agent/SKILL.md.