Second Shift

Second Shift is a local-first, notch-native macOS focus companion for people who work across multiple projects and AI agents. It remembers what changed, where work stopped, what remains blocked, and the most useful next action for the time available.

Its core ritual is Brief → Focus → Debrief. The notch is the primary interface; a detachable workspace remains available for longer reading and configuration.

The Problem

AI-assisted work is easy to start and hard to resume. Decisions remain in one agent, unfinished work in another, and deadlines in Calendar or Reminders. Second Shift turns those scattered traces into one answer: what deserves my attention now, and where exactly did I leave off?

What You Can Do

• Capture an idea with text, voice, or the global Quick Capture shortcut.
• Click the MacBook notch or companion sprite to reveal the complete daily workflow; moving away collapses it.
• Receive completed-turn context automatically from Codex, Claude Code, and Hermes through local hooks and MCP tools.
• See adapter health, last sync, hook state, missing setup, and repair actions for Codex, Claude Code, Hermes, Cursor, and OpenCode.
• Read technical agent updates as plain-language titles, short key points, why they matter, and one concrete next action.
• Review new captures in Inbox, then move them into a globally searchable Knowledge base spanning every stored date and source.
• Ask Codex questions across the local memory library or about one memory.
• Get an evidence-based next action, active blocker, deferred topics, and a compact Resume Context instead of another generic summary.
• Run a focused shift from the notch with a timer, a three-step plan, quick notes, and a clear debrief.
• See calm, truthful source activity only when work meaningfully changes.
• Search memories, projects, calendar context, voice captures, and normalized agent updates from the existing Inbox and Knowledge search field.
• Ask why a recommendation appeared and see concise reasons backed by its actual Context Events.
• Find an uninterrupted focus window, move a focus block, reschedule unfinished work, or add a follow-up only after explicit confirmation.
• Remember each project's repository, apps, files, links, preferred agent, and preferred calendar.
• Optionally enable Gentle Focus Awareness and once-daily commitment resurfacing with quiet hours; both are off by default.
• Review prior sessions as calm Shift Replay rows with duration, completed steps, captured thoughts, remaining work, and the recommended continuation.
• Load or reset a fictional demo workspace directly from Today or Settings.
• Use the floating companion for low-friction reminders while the panel is collapsed.
• Choose Memo, Nimbus, or Luma; every companion includes idle, blink, thinking, alert, listening, sleeping, happy, and concerned expressions.

Demo Flow

1. Click Load Demo Workspace on Today.
2. Choose an available-time window and prepare the pre-shift brief.
3. See an old unresolved blocker outrank a newer trivial thought.
4. Start the shift, complete a plan step, and capture a quick note.
5. End the shift and confirm the debrief.
6. Review how completed work disappears while unresolved work stays open.

Current Intelligence Flow

voice / text / Codex / external agent handoff
                    |
              raw local context
                    |
          Codex event normalization
                    |
          structured ContextEvents
                    |
          project-state reconciliation
                    |
 evidence engine / deduplication / explainability
                    |
 recommendation / resume context / open loops / mascot

Raw context, normalized events, and project states are stored locally in SQLite. Only bounded excerpts selected for normalization or reconciliation are sent through the signed-in Codex runtime.

Plain-Language Context Editor

Agent evidence is never overwritten. Second Shift stores an optional cached plain-language view beside the original title and body:

• one short header;
• up to two simple key points;
• why the update matters;
• one concrete next action.

New meaningful agent imports enter a local processing queue automatically. Second Shift processes at most three historical items at launch. The explicit Clean Up Inbox preview can deterministically simplify the remaining useful items and identify obvious historical noise before anything is archived. Codex enhancement is capped to a bounded subset, so cleanup does not create an unlimited background-usage loop. Every simplified detail retains a View original agent evidence disclosure.

Codex Setup

Second Shift defaults to Codex and reuses the Codex CLI login:

codex login status

If needed, authenticate with:

codex login

This path uses eligible Codex access associated with the signed-in ChatGPT account. It does not require an OpenAI Platform API key. Direct API-key support is reserved as an optional later provider.

Second Shift pins semantic reconciliation and session planning to the ChatGPT-account-compatible gpt-5.4-mini with low reasoning to conserve usage. Deterministic lifecycle policy still controls completion and reopening, and this does not change the global model used by the Codex app or CLI.

Gemma remains available in Settings as an offline local chat fallback through an Ollama-compatible endpoint.

First-Run Setup

On first launch, Second Shift asks each user to:

1. Choose a local display name.
2. Select which local agents to connect: Codex, Claude Code, and/or Hermes.
3. Choose their own AI provider: signed-in Codex, a local Ollama-compatible model, or their own OpenAI API key.
4. Optionally load fictional judge demo data.

OpenAI API keys are stored only in macOS Keychain. They are never written to SQLite, UserDefaults, logs, exported memories, or this repository. Local model users supply their own endpoint and installed model. Agent hooks write only to the user's local ~/Documents/Memory Companion/Agent Inbox/ folder.

The packaged app includes the local bridge installers. Settings can be used to change AI providers after onboarding.

Build and Run

./script/build_and_run.sh --verify

The packaged app is created at:

dist/MemoryCompanion.app

Its visible macOS name is Second Shift.

Five-Minute Judge Path

1. Build and launch with ./script/build_and_run.sh --verify on macOS 14 or later.
2. Open Second Shift from the MacBook notch or its floating companion.
3. Select Load Demo Workspace on Today. The sample data is fictional and does not require an API key or connected agent.
4. Choose a time window, inspect Why this?, and select Prepare My Shift.
5. Start the shift, complete a step, capture a note, and end the shift to see the debrief update the next recommendation.
6. Use Reset Demo Workspace in Settings to restore the user's normal local workspace or reset the fictional data for another test run.

Optional Codex, agent, Apple Notes, Calendar, Reminders, and Composio features use the judge's own accounts and permissions. No author credentials are included or required for the core demo.

Hackathon Build Without An Apple Developer Account

The release script produces an ad-hoc-signed ZIP and verifies its signature:

./script/build_and_run.sh --package

Output:

dist/SecondShift-macOS.zip

Judges may also download the prebuilt prototype from the build-week-2026 GitHub release.

Ad-hoc signing does not require a paid Apple Developer account. It preserves the bundle's integrity but is not Apple notarization, so Gatekeeper may warn a judge after downloading it. The recommended submission is the public source repository plus demo video, with this ZIP as an optional downloadable build. Exact judge installation steps and limitations are documented in docs/hackathon/INSTALL_WITHOUT_NOTARIZATION.md.

Agent Handoffs

Give another local agent the instructions in docs/agent-memory-handoff.md. Handoff files written to the following folder are imported into both the inherited memory library and the Second Shift Context Bus:

~/Documents/Memory Companion/Agent Inbox/

Codex, Hermes, and Claude Code are also connected through the local second-shift MCP server and end-of-turn hooks. After installation, meaningful completed agent turns flow into that inbox automatically. Agents may also call record_context explicitly when they need to preserve a precise decision or next action, and get_project_state when they need Second Shift's current understanding of a project.

The bridge lives in Tools/second-shift-bridge/ and has no third-party runtime dependencies. Run its isolated check with:

node Tools/second-shift-bridge/smoke-test.mjs

Screen-aware Quick Capture

Screen context is opt-in under Settings. When enabled, Second Shift captures the frontmost window only after Quick Capture is triggered, runs OCR locally with Apple Vision, and immediately discards the image. The resulting app, window, and short text context can be removed from the capture before saving. There is no continuous screen monitoring.

Optional Apple Notes Connector

In Settings > Connections, enable Apple Notes, grant macOS Automation access, and choose the folders Second Shift may read. Sync imports only new or changed notes, stores them locally in Unsorted for review, and refreshes every ten minutes while enabled. It does not duplicate the user's complete Notes library.

Optional Composio Connector

Composio is an opt-in connector layer, not a second memory store. Settings offers a tightly allowlisted gallery for GitHub, Linear, Notion, Gmail, Slack, Google Drive, and Google Tasks. Each connection uses the user's own Composio API key and hosted authorization flow; no app is connected by default.

The first durable ingestion adapter is deliberately narrower: it accepts only merged GitHub pull requests and closed issues. Comments, minor edits, open issues, and all other GitHub activity are ignored.

Configure a user-owned Composio workflow URL in Settings that returns a minimal JSON array:

[{"kind":"pull_request","repository":"owner/repo","number":42,"title":"Finish context bridge","state":"merged","merged":true,"url":"https://github.com/...","projectHint":"Second Shift","occurredAt":"2026-07-15T10:00:00Z"}]

The API key is stored in macOS Keychain. The app persists only the normalized context required for reconciliation, not complete external histories. The other gallery apps are connection-ready; their app-specific relevance and normalization adapters remain intentionally separate so enabling a connection cannot become an unfiltered data firehose.

Verification

swift test

The 129-test Swift suite covers local persistence, Inbox review behavior, bounded Context Bus retrieval, event normalization, evidence-protected reconciliation, malformed-model fallback, stalled memories, agent handoffs, plain-language evidence preservation, cleanup safety, confirmed-only calendar writes, schedule-noise filtering, activity truthfulness, notch geometry, demo reset behavior, and the complete focus lifecycle.

The dependency-free MCP/hook bridge has a separate smoke test:

node Tools/second-shift-bridge/smoke-test.mjs

How Codex Accelerated The Build

Codex was used as the primary engineering agent throughout Build Week. It inspected and stabilized the inherited SwiftUI app, designed the Context Bus, implemented strict normalization and reconciliation boundaries, added the signed-in Codex app-server integration, built the cross-agent MCP/hook bridge, fixed responsive navigation and interaction regressions, and created the test and submission evidence. The commit boundary at 60092e6 separates the pre-existing companion from the Build Week implementation.

GPT-5.6 powered the Build Week engineering and product-audit sessions. The shipping app deliberately uses bounded gpt-5.4-mini prompts for private runtime normalization, reconciliation, and focus planning; that model choice is an explicit product cost decision, not a limitation of the implementation.

Privacy

Memories, raw context, events, and project state remain in local SQLite. The agent bridge writes local Markdown files and has no cloud dependency. When Codex intelligence is enabled, only bounded excerpts required for a specific normalization or reconciliation request leave the Mac through the user's existing signed-in Codex session.

Hackathon Evidence

The pre-existing app and Build Week additions are separated by commits and documented in docs/hackathon/.

• docs/hackathon/DEMO_SCRIPT.md contains the three-minute recording plan.
• docs/hackathon/SUBMISSION_BRIEF.md maps the product to the judging criteria and lists the remaining submission work.

License

Second Shift is available under the MIT License. See LICENSE.