cortexshift 0.1.0__tar.gz

cortexshift-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# CortexShift project-local state
+.cortexshift/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.venv/
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Testing and coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+
+# Type checking and linting
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+dmypy.json
+
+# Operating System
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# IDE and editors
+.idea/
+.vscode/
+*.swp
+*.swo
+*~

cortexshift-0.1.0/AGENTS.md

@@ -0,0 +1,101 @@
+# AGENTS.md — CortexShift Contributor Contract for Coding Agents
+
+Welcome to **CortexShift**. This repository is built to orchestrate and transition work across multiple coding agents (Claude Code, OpenAI Codex, Google Antigravity, and future agents). Because CortexShift itself will be developed, maintained, and refactored by different AI coding agents, all participating agents MUST follow this engineering contract.
+
+---
+
+## 1. Prime Directive: Truth Hierarchy
+
+Never treat an agent summary, commit message, or handoff note as infallible truth. Adhere strictly to the truth hierarchy:
+
+1. **Actual repository files** (the filesystem is primary reality)
+2. **Git state** (branch, commits, status, diffs)
+3. **Verified command/test results** (executed by you in this session)
+4. **CortexShift canonical task state** (persisted task records)
+5. **Previous agent summaries/handoffs** (advisory only)
+
+A previous agent statement claiming "all tests pass" must NEVER override your own test execution revealing failures. Always verify.
+
+---
+
+## 2. Architectural Invariants
+
+Every agent working on CortexShift must preserve the following architectural invariants:
+
+1. **Task-Centric, Not Conversation-Centric**: Tasks belong to CortexShift, not to any provider session. Providers are ephemeral workers on a persistent task.
+2. **Native-Agent-First**: Never re-implement provider CLIs. CortexShift orchestrates native CLIs through adapters.
+3. **Provider-Agnostic Core**: The domain and application layers must NEVER contain provider-specific conditionals (e.g. `if provider == "claude"`). All provider variance belongs strictly behind the `ProviderAdapter` port.
+4. **Same-Working-Tree Model**: Agents operate sequentially in the same local repository worktree. Do not design mechanisms around copying or duplicating repositories.
+5. **Single Mutating Agent**: Only one coding agent may actively mutate the workspace at a time. Multi-agent concurrent editing is strictly out of scope.
+6. **Local-First & Zero Telemetry**: Core functionality must run locally without cloud dependencies, mandatory hosted backends, external databases, or telemetry.
+7. **Zero Credential Storage**: CortexShift MUST NEVER capture, store, or manage provider API keys or auth tokens. Authentication is strictly delegated to each provider's native CLI.
+8. **Structured Canonical State over Transcripts**: Context handoff uses distilled structured state (objective, requirements, decisions, touched files, test status). Transcript capture is disabled by default (`capture_transcripts = false`).
+9. **Git Snapshot Authority vs. Reality**: Stored `GitSnapshot` records are immutable historical observations of what was true at capture time. They are never proof of current working tree reality once subsequent changes occur. Live inspection via `git status` outranks any stored snapshot.
+10. **Strictly Read-Only Git Execution**: CortexShift's repository inspection must never mutate the repository's version control state. All repository inspection commands (`git status`, `git branch`, `git rev-parse`, `git diff --shortstat`) must be strictly read-only (no `git add`, `git commit`, `git checkout`, `git reset`, `git clean`, etc.).
+11. **Direct Terminal Passthrough & Zero Prompt Storage**: Native provider interactive sessions directly inherit terminal stdio without pipe-wrapping, buffering, or TUI scraping. CortexShift must never persist user prompts, conversational transcripts, or provider auth tokens.
+12. **Mandatory Workspace Lease**: All mutating agent operations strictly require an exclusive project workspace lease (`FileWorkspaceLease` via OS advisory locking on `.cortexshift/agent.lock`) to enforce single-mutating-agent execution. The OS advisory lock (`fcntl.flock` / `msvcrt.locking`) on the open file descriptor is authoritative; the mere existence of the lock file on disk does not imply an active lease, and users must never be instructed to delete the lock file. Stale database session records never impede acquiring a free OS lock.
+13. **Handoff Generation Must Not Require the Outgoing Provider**: Canonical handoffs are derived deterministically from durable local state (canonical Project, canonical Task, previous Session metadata, live Git inspection, persisted Git snapshot). CortexShift must NEVER require the outgoing agent to summarize its work, launch, or even be installed — the moment a user most needs to switch is the moment the previous agent can no longer answer. No outgoing model call may ever become a mandatory handoff step.
+14. **Historical Handoff State Never Substitutes for Live Repository Truth**: A stored `HandoffRecord` is an immutable observation of what was true at capture time. Live repository files, live Git state, and verified test results always outrank it. Never present recorded completed items as proven, and never present a stored Git snapshot as current truth.
+15. **Unknown State Stays Explicitly Unknown**: Where CortexShift has no verified record (currently `IMPORTANT DECISIONS` and `TEST STATUS`), encode the absence honestly. Never infer that tests pass because a provider process exited 0.
+16. **Provider-Specific Handoff Delivery Belongs Behind Adapters**: All transport variance lives behind `ProviderHandoffAdapter`. Orchestration services must never branch on provider identity.
+17. **Never Persist Rendered Prompts or Provider Responses**: Canonical structured state is persisted; rendered provider prompts, provider bootstrap responses, transcripts, and hidden reasoning are not. Rendered packages are transport representations, re-derived deterministically from canonical state.
+
+18. **Exact Native Identity Only**: Never guess provider-native session identity or inspect provider transcript/cache storage to discover sessions.
+19. **Fresh Context on Return**: Fresh canonical handoff and live repository state outrank stale native conversation assumptions.
+20. **Invocation Lineage**: Every resume invocation creates a new CortexShift Session record; preserve historical invocations.
+21. **Historical Checkpoint State Never Outranks Live Truth**: Checkpoint records are immutable historical observations at capture time. Live repository files, live Git status, and verified test results strictly outrank any historical checkpoint.
+22. **Zero Outgoing Model Calls for Checkpoints & Recovery**: Checkpoint creation and crash recovery are entirely deterministic and derived from durable local state and live repository inspection. CortexShift must never invoke any LLM or require the outgoing provider to summarize its state during checkpoint or recovery.
+23. **Never Fabricate Test Verification or Process End Times**: If tests are reported in a checkpoint, they are explicitly tagged as unverified reported provenance. When reconciling stale sessions, CortexShift records `status=interrupted`, `exit_reason=unexpected_termination`, and `reconciled_at=<timestamp>`, leaving `ended_at=None` to avoid fabricating an unobserved process termination time.
+24. **Cooperative Milestone Checkpoints Without Lease**: Agents and operators may capture cooperative milestone checkpoints (`cortexshift checkpoint create`) while a provider session is actively running without acquiring the exclusive workspace lease. Crash recovery (`cortexshift recover`) strictly requires acquiring the exclusive workspace lease to ensure no other agent is actively modifying the repository.
+25. **Pure Stdout Wire Protocol for MCP**: Standard output (`stdout`) of `cortexshift mcp serve` is strictly and exclusively reserved for valid MCP JSON-RPC protocol frames. All diagnostic logging, notices, and errors are routed strictly to `stderr` or silenced. Polluting `stdout` breaks client JSON-RPC parsers.
+26. **Workspace Lease Bypass for MCP Operations**: Because an active provider session already holds the exclusive workspace lease (`.cortexshift/agent.lock`), MCP server operations initiated by that agent deliberately bypass the lease to avoid self-deadlocks. Process and thread safety are guaranteed by SQLite WAL concurrency.
+27. **Bound Context Isolation**: MCP operations are bound strictly at launch to a specific `Project`, `Task`, `Session`, and `ProviderId`. Tool mutations affect only the task assigned at launch, preventing cross-task state corruption regardless of external changes to the default active task.
+
+28. **Interface Adapters Reuse Application Services**: The CLI, the MCP server, and the TUI are peer interface adapters over one set of application services. None of them may contain SQL, open a persistence store directly, invoke Git, construct provider arguments, or duplicate task, recovery, or handoff rules. A rule needed by two adapters belongs in the domain or application layer, not copied into both.
+
+29. **CortexShift Releases Terminal Ownership Before Launching a Native Provider**: Provider-native terminal UIs are never embedded, scraped, multiplexed, or relayed through a pseudo-terminal. The TUI exits with a structured `TuiExitRequest`, and only after the Textual application's run loop has returned may the run/resume/switch service be invoked. No PTY or terminal-emulator dependency (`pexpect`, `ptyprocess`, `pyte`, tmux wrappers) may be introduced.
+
+30. **The Dashboard Must Not Hold the Workspace Lease**: An open TUI must never block a coding agent. Observation and cooperative editing acquire no lease; operations requiring exclusivity (run, resume, switch, recover) acquire it inside their own services, which are the authority on refusing unsafe attempts. Workspace activity is probed through the OS advisory lock and never inferred from the lock file's existence.
+
+31. **Historical State Is Labelled Honestly and Never Presented as Live Truth**: Every human-facing surface states the authority of what it shows — live repository inspection, historical checkpoint or handoff observation, reported-and-unverified test status, or last-known session state. Unfinalized sessions are never asserted as crashed, and progress is never inferred from Git state or a process exit code.
+
+---
+
+## 3. Engineering & Workflow Rules
+
+- **Read Before Modifying**: Review [`docs/architecture.md`](docs/architecture.md) and relevant ADRs in [`docs/decisions/`](docs/decisions/) before initiating significant architectural modifications.
+- **Strict Layering**: Enforce dependency flow: `domain` ← `ports` ← `application` ← `cli` / `adapters`. Domain must never import CLI, concrete adapters, or third-party infrastructure frameworks.
+- **Persistence Boundaries**: Domain, application, and CLI layers must NEVER contain SQL statements or SQLite dependencies. All persistence logic belongs strictly behind ports in adapters (`SQLiteStateStore`).
+- **Data Integrity & Non-Destruction**: Never automatically wipe, reset, or silently overwrite user database state. Migrations must be forward-safe, deterministic, and transactional. If state is incompatible, fail safely.
+- **Private State Area**: `.cortexshift/` is local private runtime state. It must never store provider credentials, auth tokens, or conversational transcripts.
+- **Minimal Dependencies**: Do not introduce heavy frameworks (no LangChain, LlamaIndex, vector DBs, Redis, ORMs, or cloud SDKs). Rely on Python stdlib, Pydantic, Typer, Rich, the official MCP SDK, and Textual. Exactly one TUI framework: do not add `prompt_toolkit`, `urwid`, `blessed`, or curses wrappers alongside Textual.
+- **Tests Are Mandatory**: Every new domain behavior, CLI command, and adapter must include automated, deterministic unit tests. Run `pytest`, `ruff check .`, and `mypy src` before declaring work complete.
+- **Scope Discipline**: Strictly keep changes scoped to the current phase and requested task. Do NOT prematurely implement future roadmap phases (e.g., do not add provider execution or database schemas until requested).
+- **Document Changes**: When modifying architecture or adding cross-cutting features, record an Architectural Decision Record (ADR) in `docs/decisions/` and update relevant documentation.
+- **Never Silently Alter Invariants**: Any change to foundational rules requires explicit rationale, consensus, and an updated ADR.
+
+---
+
+## 4. Key Documentation Links
+
+- [Architecture Overview](docs/architecture.md)
+- [Canonical Handoff Protocol](docs/handoff-protocol.md)
+- [Project Roadmap](docs/roadmap.md)
+- [Architecture Decisions (ADRs)](docs/decisions/ADR-0001-core-architecture.md)
+  - [ADR-0001: Core Architecture](docs/decisions/ADR-0001-core-architecture.md)
+  - [ADR-0002: Safe Provider Discovery](docs/decisions/ADR-0002-safe-provider-discovery.md)
+  - [ADR-0003: Project-Local Persistence](docs/decisions/ADR-0003-project-local-persistence.md)
+  - [ADR-0004: Git Repository Context](docs/decisions/ADR-0004-git-repository-context.md)
+  - [ADR-0005: Native Provider Launch & Session Lifecycle](docs/decisions/ADR-0005-native-provider-runtime.md)
+  - [ADR-0006: Canonical Agent Handoff & Manual Provider Switching](docs/decisions/ADR-0006-canonical-agent-handoff.md)
+  - [ADR-0007: Native Session Continuity](docs/decisions/ADR-0007-native-session-continuity.md)
+  - [ADR-0008: Checkpoints, Crash Recovery & Handoff Enrichment](docs/decisions/ADR-0008-checkpoint-and-recovery.md)
+  - [ADR-0009: MCP Shared State & Agent Self-Reporting](docs/decisions/ADR-0009-mcp-shared-state.md)
+  - [ADR-0010: Interactive Terminal Control Center](docs/decisions/ADR-0010-terminal-control-center.md)
+
+## Release contracts
+
+- Published SQLite migrations are immutable.
+- Published handoff/checkpoint protocol semantics are versioned contracts.
+- Release workflows use least privilege and no long-lived PyPI tokens.
+- Public privacy/provider-support claims must not exceed verified code behavior.

cortexshift-0.1.0/CHANGELOG.md

@@ -0,0 +1,55 @@
+# Changelog
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html),
+with compatibility care for commands, persisted state, and MCP contracts during 0.x.
+
+## 0.1.0 — Unreleased release candidate
+
+Initial public alpha; no publication date has been assigned.
+
+### Added
+
+- Project-local SQLite tasks with objectives, requirements, structured progress,
+  known issues, and durable history.
+- Passive discovery and native terminal orchestration for Claude Code, Codex,
+  and Antigravity through provider adapters.
+- Deterministic canonical handoffs, manual switching, exact known-ID resume,
+  and fresh context on return to a provider.
+- Cooperative milestone and session-end checkpoints, plus deterministic crash
+  recovery with honest historical observations and reported test provenance.
+- Local stdio MCP shared state and a keyboard-driven Textual control center.
+- Release metadata with verified canonical project URLs, wheel/sdist content
+  validation, installed CLI/MCP/TUI tests, isolated pipx tests, cross-platform CI,
+  OIDC release machinery, and public guides.
+
+### Safety and compatibility
+
+- Same working tree, exclusive provider workspace lease, read-only Git inspection,
+  provider-native permissions, and no outgoing model call for handoff/recovery.
+- No provider credentials, prompts, rendered handoffs, responses, transcripts,
+  full patches, telemetry, self-updater, or cloud account stored/introduced.
+- SQLite schema v6, Handoff Protocol v1, and Checkpoint Protocol v1 are preserved.
+- Provider CLI behavior remains external, and real-provider validation stays a
+  maintainer gate: Claude Code and Codex are validated end to end, while
+  Antigravity rests on automated fake-provider coverage only.
+
+### Fixed
+
+- Preserve architectural decisions across handoffs. Handoffs read decisions from the
+  newest checkpoint alone, so any later checkpoint recorded without decisions of its
+  own — including the session-end checkpoint captured automatically when a provider
+  exits — buried every decision recorded during that session, and the package then
+  stated that no structured decisions were recorded. `HandoffBuilder` now aggregates
+  decisions across the task's whole checkpoint history in chronological first-seen
+  order, de-duplicated by exact string equality and scoped strictly to one task.
+  Checkpoints remain immutable point-in-time records and are not rewritten;
+  `record_decision` additionally carries a structured `trigger="decision"` marker in
+  existing checkpoint metadata. Schema v6, Checkpoint Protocol v1, and Handoff
+  Protocol v1 are unchanged.
+- Bind the managed CortexShift session inside the per-launch MCP configuration.
+  A provider CLI spawns the MCP server, and Codex starts MCP servers with a
+  sanitized environment, so managed Codex sessions previously saw `session: null`
+  and only the four read tools. Unmanaged MCP stays read-only.
+- Escape Windows/quoted Python paths in Codex MCP configuration.
+- Safely probe existing empty Windows workspace lock files without double-close.
+- Close subprocess pipes in test helpers and run fake Python providers portably.

cortexshift-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,159 @@
+# Contributing to CortexShift
+
+Thank you for your interest in contributing to **CortexShift**! We are building a local, provider-agnostic developer tool that lets software development tasks transition smoothly between coding agents without context loss.
+
+Whether you are a human developer or an AI coding agent, please review these guidelines.
+
+---
+
+## Development Environment Setup
+
+CortexShift targets **Python 3.12+** and uses **[`uv`](https://docs.astral.sh/uv/)** as its primary package and project manager.
+
+### 1. Obtain the source
+
+Clone the canonical public repository:
+
+```bash
+git clone https://github.com/batuhanasmakaya/CortexShift.git
+cd CortexShift
+```
+
+An extracted source distribution works equally well for verification builds.
+
+### 2. Install Dependencies
+
+Using `uv`:
+
+```bash
+uv sync --locked
+```
+
+This creates a local `.venv` and installs all runtime and development dependencies.
+
+---
+
+## Quality & Verification Commands
+
+We maintain strict standards for code quality, typing, and testing. Run the following checks before opening a pull request or completing an agent task:
+
+### 1. Code Formatting & Linting
+
+```bash
+uv run ruff check .
+uv run ruff format --check .
+```
+
+To automatically fix safe issues:
+
+```bash
+uv run ruff check --fix .
+uv run ruff format .
+```
+
+### 2. Type Checking
+
+Mypy is configured in strict mode:
+
+```bash
+uv run mypy
+```
+
+### 3. Automated Tests & Coverage
+
+```bash
+uv run pytest
+```
+
+Tests that invoke the CLI must use `AnsiFreeCliRunner` (or `run_cli`, for subprocesses)
+from `tests/cli_runner.py` rather than `typer.testing.CliRunner` or a bare
+`subprocess.run`. Typer renders help through Rich and forces color whenever
+`GITHUB_ACTIONS`, `FORCE_COLOR`, or `PY_COLORS` is set, which splits option names across
+escape sequences — `--json` stops being a substring of the help text. The shared runners
+strip those escapes so assertions describe what the command said, not how the terminal
+painted it. To reproduce CI's rendering locally:
+
+```bash
+FORCE_COLOR=1 uv run pytest
+```
+
+Terminal width stays whatever the caller asked for — `COLUMNS=60 uv run pytest` really
+does run the CLI at 60 columns — so assertions have to cope with it themselves:
+
+- When Rich merely re-wraps a sentence, pass the output through `unwrapped()` from
+  `tests/cli_runner.py` instead of matching a fragment that happens to fit on one line.
+- When a test asserts on a laid-out table or grid, request the `fixed_console_width`
+  fixture. A narrow terminal makes the CLI genuinely truncate cells, and no
+  normalization can recover dropped characters. Use it only for that.
+
+```bash
+COLUMNS=60 uv run pytest
+COLUMNS=200 uv run pytest
+```
+
+### 4. CLI Smoke Testing
+
+```bash
+uv run cortexshift --help
+uv run cortexshift version
+uv run python -m cortexshift --help
+```
+
+---
+
+## Architectural Principles & Boundaries
+
+All contributors must respect the core architectural layers:
+
+```text
+src/cortexshift/
+├── domain/       # Pure business entities & value objects (zero external frameworks)
+├── ports/        # Protocols & abstract interfaces defining contracts
+├── application/  # Orchestration, use-cases, and business workflows
+├── adapters/     # Implementations of ports (CLI wrappers, persistence, etc.)
+└── cli/          # Typer/Rich command-line interface entrypoints
+```
+
+### Critical Guidelines
+
+1. **Dependency Inversion**: Dependencies point inward:
+   - `domain` must never import from `adapters`, `cli`, or third-party infrastructure frameworks.
+   - `ports` define interfaces using domain types.
+   - `adapters` implement `ports`.
+2. **Provider Isolation**: Provider-specific logic (for Claude Code, Codex, Antigravity, etc.) must reside exclusively in `src/cortexshift/adapters/providers/`. Never introduce provider conditionals in `domain` or `application`.
+3. **No Credential Storage**: CortexShift never stores, reads, or manages provider API keys. Native CLIs handle their own auth.
+4. **Minimal Runtime Dependencies**: Do not introduce heavy AI frameworks (LangChain, LlamaIndex), vector databases, or ORMs.
+5. **Truth Hierarchy**: Real repository files, Git state, and verified test executions outrank agent summaries.
+6. **Architectural Decision Records (ADRs)**: Any architectural change, new invariant, or cross-cutting dependency addition requires an ADR in `docs/decisions/`.
+
+---
+
+## Commit & PR Guidelines
+
+- Keep pull requests focused on a single phase or feature.
+- Include unit tests covering all new domain behavior, ports, and CLI commands.
+- Ensure all CI checks pass on GitHub Actions.
+- Open issues and pull requests at
+  <https://github.com/batuhanasmakaya/CortexShift>. Report suspected
+  vulnerabilities through [Security](SECURITY.md) instead of a public issue.
+
+## Provider adapters and persistence
+
+Implement discovery, runtime, handoff, and optional native-session ports in
+`adapters/providers`; register adapters at the composition boundary. Add bounded
+version/help checks and deterministic fakes, never CI model calls. Do not add
+provider conditionals to domain/application code. CLI, MCP, and TUI reuse services.
+
+Persistence and SQL belong in adapters. Published migrations v1–v6 must remain
+unchanged; add transactional forward migrations with rollback and preservation
+tests. Published handoff/checkpoint meanings require explicit protocol versioning.
+Never persist credentials, prompts, provider responses, transcripts, or full patches.
+
+## Release checks
+
+Run `uv run python scripts/release_check.py`, `uv build`, and
+`uv run python scripts/artifact_smoke.py --dist dist`. The latter creates disposable
+install environments and uses package-index access for dependencies. It never calls
+models or publishes. See [Releasing](docs/releasing.md) for the complete sequence.
+Pre-1.0 internal Python imports are not a stable public API. Changes to commands,
+persisted state, and MCP contracts need explicit compatibility review.

cortexshift-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CortexShift contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cortexshift-0.1.0/PKG-INFO

@@ -0,0 +1,202 @@
+Metadata-Version: 2.5
+Name: cortexshift
+Version: 0.1.0
+Summary: Provider-neutral coding-agent handoffs with persistent project context.
+Project-URL: Homepage, https://github.com/batuhanasmakaya/CortexShift
+Project-URL: Repository, https://github.com/batuhanasmakaya/CortexShift
+Project-URL: Issues, https://github.com/batuhanasmakaya/CortexShift/issues
+Project-URL: Changelog, https://github.com/batuhanasmakaya/CortexShift/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/batuhanasmakaya/CortexShift/security
+Author: CortexShift contributors
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,antigravity,claude-code,codex,coding-agents,context-handoff,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.12
+Requires-Dist: mcp<3,>=2
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: rich>=13.7.0
+Requires-Dist: textual<9,>=8
+Requires-Dist: typer>=0.12.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.4.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# CortexShift
+
+**Switch agents. Keep the context.**
+
+CortexShift keeps development tasks intact as you move between Claude Code,
+Codex, and Antigravity in the same local repository. A Task belongs to CortexShift;
+providers are workers over that Task. Switching does not require the outgoing
+agent to answer, summarize, or even remain installed.
+
+**0.1.0 is an initial public alpha release candidate. PyPI publication is pending.**
+The canonical repository is <https://github.com/batuhanasmakaya/CortexShift>.
+Python 3.12–3.14 is targeted, with required Linux/macOS/Windows CI on protected
+`main`. Real end-to-end validation is complete for Claude Code and Codex;
+Antigravity has automated coverage only, and interactive platform smokes remain
+on a separate maintainer checklist.
+
+## How it works
+
+CortexShift stores objectives, requirements, progress, checkpoints, and session
+metadata in project-local SQLite. It combines that structured state with live
+Git inspection to prepare a canonical handoff. A conversation transcript is not
+canonical project state: receiving agents must verify the files and run tests.
+
+Authority flows from live repository files → live Git → verified evidence →
+canonical Task state → historical observations. Recorded completion is a report,
+not proof; checkpoints never establish that tests passed independently.
+
+## Capabilities
+
+- Persistent tasks, provider session history, and manual agent switching.
+- Exact native resume when an ID is known; fresh canonical context on return.
+- Cooperative checkpoints and deterministic crash recovery.
+- MCP shared state over local stdio: agents can read context and report progress.
+- A keyboard-driven terminal control center for tasks, repository state, and history.
+- Read-only Git inspection and an OS workspace lock for exclusive provider runs.
+
+## Quick start
+
+After PyPI publication:
+
+```bash
+pipx install cortexshift
+cd my-project
+cortexshift doctor
+cortexshift init
+cortexshift task start --title "Implement authentication" \
+  --objective "Add authentication without breaking existing APIs."
+cortexshift run claude
+# After the provider exits:
+cortexshift switch codex
+cortexshift tui
+```
+
+CortexShift does not bundle Git or any provider CLI. Install and authenticate
+native providers yourself. Git is recommended for repository-aware handoffs,
+but project initialization also works without Git.
+
+## Installation and updates
+
+[pipx](https://pipx.pypa.io/stable/) gives a global command with isolated Python
+dependencies. Use Python 3.12 or newer. Once published:
+
+```bash
+pipx upgrade cortexshift
+pipx uninstall cortexshift
+```
+
+Before publication, clone the repository and use `uv sync --locked`, then
+`uv run cortexshift --help`:
+
+```bash
+git clone https://github.com/batuhanasmakaya/CortexShift.git
+cd CortexShift
+```
+
+To install a candidate globally without an editable checkout: `uv build`, then
+`pipx install dist/cortexshift-0.1.0-py3-none-any.whl`.
+A virtualenv/pip alternative is in [Getting Started][getting-started].
+Homebrew is pending publication of a custom tap.
+
+## Your first handoff
+
+```bash
+cortexshift checkpoint create -d "Preserve existing API compatibility" \
+  -t "Targeted tests passed (operator report)"
+cortexshift handoff preview codex
+cortexshift switch codex --dry-run
+cortexshift switch codex
+```
+
+Preview and dry-run launch no model and persist nothing. Actual Codex and
+Antigravity handoffs each use one read-only bootstrap model turn before native
+resume, which may consume provider usage. Claude receives context directly.
+
+## Terminal control center
+
+Run `cortexshift tui` in an initialized project and a real terminal. Use `1`–`7`
+to navigate, `r` to refresh, `c` to checkpoint, `x` for provider actions, and `?`
+for help. The dashboard releases terminal ownership before launching a native
+provider. After that provider exits, run `cortexshift tui` again.
+An open dashboard holds no workspace lease and may observe a running agent.
+
+## MCP and providers
+
+Claude and Codex receive MCP configuration automatically. Antigravity requires
+explicit workspace setup: `cortexshift mcp setup antigravity`.
+Inspect integration with `cortexshift mcp status`. Managed sessions expose
+10 context-bound tools; unmanaged/read-only sessions expose four read tools.
+See [Provider Support][provider-support] for identity, resume, and
+validation limits.
+
+## Privacy and trust
+
+CortexShift has no cloud account, telemetry, or paid model API key requirement.
+It does not copy provider credentials or persist prompts, provider responses,
+transcripts, or full Git patches. Native provider permissions remain authoritative.
+Providers may send repository/context data to their own services under their
+configuration and terms; local orchestration does not change that behavior.
+
+Task text, paths, and project history are local development data. Generally ignore
+`.cortexshift/` in Git; CortexShift does not rewrite your `.gitignore`.
+See [Security][security-policy] for boundaries and safe reporting.
+
+## Limitations
+
+External provider CLIs can change. Legacy or plain Codex/Antigravity runs may
+have no native ID; those sessions cannot be exact-resumed. Deleted native
+conversations are not silently replaced. There is no automatic quota switching,
+embedded provider TUI, GUI, cloud agent, secret manager, or terminal multiplexer.
+Provider accounts, subscriptions, and usage costs are governed by each provider.
+Internal Python modules are not a stable library API.
+
+## Documentation and development
+
+- [Getting Started][getting-started] and [Troubleshooting][troubleshooting]
+- [Provider Support][provider-support]
+- [Architecture][architecture] and [Handoff Protocol][handoff-protocol]
+- [Contributing][contributing], [Releasing][releasing], and [Roadmap][roadmap]
+- [Changelog][changelog] and [Issues][issues]
+
+```bash
+uv sync --locked
+uv run ruff check .
+uv run ruff format --check .
+uv run mypy
+uv run pytest
+```
+
+## License
+
+[MIT][license]. CortexShift is an independent open-source project and is not
+affiliated with or endorsed by Anthropic, OpenAI, or Google.
+
+[getting-started]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/getting-started.md
+[provider-support]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/provider-support.md
+[architecture]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/architecture.md
+[handoff-protocol]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/handoff-protocol.md
+[troubleshooting]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/troubleshooting.md
+[contributing]: https://github.com/batuhanasmakaya/CortexShift/blob/main/CONTRIBUTING.md
+[releasing]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/releasing.md
+[roadmap]: https://github.com/batuhanasmakaya/CortexShift/blob/main/docs/roadmap.md
+[changelog]: https://github.com/batuhanasmakaya/CortexShift/blob/main/CHANGELOG.md
+[security-policy]: https://github.com/batuhanasmakaya/CortexShift/blob/main/SECURITY.md
+[license]: https://github.com/batuhanasmakaya/CortexShift/blob/main/LICENSE
+[issues]: https://github.com/batuhanasmakaya/CortexShift/issues