tiennm99/ccs
1
0 Fork 0
mirror of https://github.com/tiennm99/ccs.git synced 2026-10-03 20:13:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(hygiene): remove superseded local guides

Browse Source
This commit is contained in:
Tam Nhu Tran committed 2026-07-26 09:35:42 -04:00
1 parent 4485fd6406
commit 75e715eebd
3 files changed
-648
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

docs/cursor-integration.md
-165
View File
@@ -1,165 +0,0 @@
# Cursor IDE Integration
This guide covers the deprecated CCS-owned Cursor IDE bridge, including auth import, local daemon lifecycle, live probe checks, and dashboard controls.
`ccs cursor` now belongs to the CLIProxy-backed Cursor provider path.
Use `ccs legacy cursor` for the deprecated local bridge documented here.
## What It Provides
- OpenAI-compatible local endpoint powered by Cursor credentials.
- Anthropic-compatible local endpoint at `/v1/messages` for Claude-native clients.
- Cursor model list and chat completions via the local CCS daemon.
- Dedicated dashboard page: `ccs config` -> `Deprecated` -> `Cursor IDE (Legacy)`.
## What This Runtime Actually Does
`ccs legacy cursor` does not launch Cursor IDE itself.
The current workflow is:
1. import Cursor credentials from local SQLite or manual input
2. run a local CCS daemon on `127.0.0.1:<port>`
3. launch Claude Code against that daemon
4. have CCS translate requests to Cursor upstream
Treat this as a CCS-managed Cursor bridge, not a generic CLIProxy-backed provider path.
## Prerequisites
- Cursor IDE installed and logged in.
- CCS installed and configured (`ccs config` works).
- For auto-detect auth on macOS/Linux: `sqlite3` available in PATH.
## CLI Workflow
### 1) Enable integration
```bash
ccs legacy cursor enable
```
### 2) Import credentials
Auto-detect from Cursor local SQLite state:
```bash
ccs legacy cursor auth
```
Manual fallback:
```bash
ccs legacy cursor auth --manual --token <token> --machine-id <machine-id>
```
### 3) Start daemon
```bash
ccs legacy cursor start
```
### 4) Run a live probe
```bash
ccs legacy cursor probe
```
Use this to verify that the current build can complete one real authenticated request through the local daemon.
### 5) Run Cursor-backed Claude
```bash
ccs legacy cursor "explain this repo"
```
### 6) Verify status
```bash
ccs legacy cursor status
```
Use `ccs legacy cursor` with bare or normal Claude args to run through the local Cursor proxy.
The admin namespace remains available for setup and inspection:
```bash
ccs legacy cursor help
```
### 7) Stop daemon
```bash
ccs legacy cursor stop
```
## Supported Cursor Provider Path
For the supported CLIProxy-backed Cursor provider, use:
```bash
ccs cursor --auth
ccs cursor --accounts
ccs cursor --config
ccs cursor "task"
```
## Runtime Defaults
- Default port: `20129`
- `ghost_mode`: enabled
- `auto_start`: disabled
- Model list resolution: authenticated live fetch when available, with cached/default fallback.
- Request model validation: if a requested model is not present in the available Cursor model catalog, daemon falls back to the resolved default model.
- Daemon API surface: `POST /v1/chat/completions`, `POST /v1/messages`, and `GET /v1/models`.
- Live verification: `ccs legacy cursor probe` or `POST /api/cursor/probe`
These values are managed in unified config and can be updated from CLI or dashboard.
## Dashboard Usage
Open dashboard:
```bash
ccs config
```
Then navigate to `Cursor IDE (Legacy)` in the `Deprecated` section.
Available controls:
- Integration toggle (`enabled`)
- Auth actions (auto-detect, manual import)
- Daemon actions (start/stop)
- Runtime config (port, auto-start, ghost mode)
- Models list with searchable combobox filtering for large catalogs
- Raw editor for `~/.ccs/cursor.settings.json`
## Raw Settings and Unified Config Sync
Raw settings are stored in:
`~/.ccs/cursor.settings.json`
When raw settings include a local `ANTHROPIC_BASE_URL` port override, CCS synchronizes that port back into unified config so CLI and dashboard remain consistent.
## Troubleshooting
### `Not authenticated` or `expired` in `ccs cursor status`
- Re-run `ccs legacy cursor auth` (or manual auth command).
### `ccs legacy cursor probe` fails even though status is green
- `status` proves local config/auth/daemon readiness only.
- `probe` proves the live runtime path.
- If `probe` fails with upstream protocol errors, inspect the current CCS build first rather than assuming the local daemon is healthy.
### Auto-detect fails
- Ensure Cursor is logged in.
- Confirm `sqlite3` is installed or use manual import.
- Use manual auth import if needed.
### Daemon fails to start
- Check if port `20129` is in use.
- Change port in dashboard config tab, then retry `ccs legacy cursor start`.
docs/dashboard-auth-cli.md
-267
View File
@@ -1,267 +0,0 @@
# Dashboard Authentication CLI
Last Updated: 2026-05-05
CLI commands for managing CCS dashboard authentication.
## Overview
The CCS dashboard (`ccs config`) can be protected with username/password authentication. This is useful whenever the dashboard is reachable from another device, such as when you explicitly bind it beyond loopback with `ccs config --host 0.0.0.0`.
Authentication is **disabled by default** for backward compatibility, while `ccs config` binds to `localhost` by default. Use the CLI to configure and enable auth before exposing the dashboard to other devices.
CCS does **not** ship a default dashboard username or password. When someone opens the dashboard from a non-loopback/IP address before auth is enabled, the UI now shows a setup state instead of an ambiguous login form. The host owner must run `ccs config auth setup`, or the user should switch back to the localhost URL if they are on the same machine.
Docker note: the integrated `ccs docker` stack stores its config inside the running container volume, not in the outer shell's `~/.ccs`. For Docker deployments, run auth setup inside the container:
```bash
docker exec -it ccs-cliproxy ccs config auth setup
```
When auth stays disabled, CCS now applies a localhost-only fallback on sensitive management endpoints. Remote devices can still open the dashboard UI when you intentionally bind it beyond loopback, but write-capable routes such as AI Provider management and CLIProxy auth/status helpers reject non-loopback requests until you enable dashboard auth.
## Account Context Modes (Related Feature)
Dashboard auth and account context metadata are separate:
- `dashboard_auth`: protects dashboard access with username/password
- `accounts.<name>.context_mode/context_group`: controls isolated vs shared account context
- `accounts.<name>.shared_resource_mode`: controls plugins/commands/skills/agents/settings.json sharing
Account context is isolation-first. The recommended two-account route is:
```bash
ccs auth create work
ccs auth create personal
ccs work
ccs personal
```
Only enable history sync when both accounts should share local continuity while tokens stay separate:
| Mode | Default | Requirement |
|------|---------|-------------|
| `isolated` | Yes | No `context_group` required |
| `shared` | No (opt-in) | Valid non-empty `context_group` |
Shared continuity depth:
- `standard` (default): shares project workspace context only
- `deeper` (advanced opt-in): also syncs `session-env`, `file-history`, `shell-snapshots`, `todos`
`ccs auth show <profile>` reports credential isolation, shared resource mode, settings sync state, history lane, and whether plain `ccs` currently uses the same resume lane.
Non-bare account profiles share Claude-local resources with native Claude:
```text
~/.ccs/instances/<profile>/settings.json -> ~/.ccs/shared/settings.json -> ~/.claude/settings.json
```
This keeps ordinary Claude settings, plugins, commands, skills, and agents in sync without copying account tokens. Existing accounts can opt out or back in:
```bash
ccs auth resources work --mode profile-local
ccs auth resources work --mode shared
```
Local history is separate: if users want future plain `ccs` and `ccs ck` sessions to resume from the same account lane, run `ccs auth default ck` after backing up the current native lane with `ccs auth backup default`.
`context_group` normalization and validation:
- trim + lowercase + collapse internal whitespace to `-`
- allowed characters: lowercase letters, numbers, `_`, `-`
- must start with a letter
- max length: 64
- shared mode requires non-empty value after normalization
- `continuity_mode` is only valid when mode is `shared`
`PUT /api/config` behavior for account context:
- rejects invalid unified payloads
- rejects explicit `context_mode: shared` with invalid/empty `context_group`
- rejects invalid `continuity_mode` values
- normalizes valid shared `context_group` before save
- defaults missing shared `continuity_mode` to `standard`
- rejects `context_group` when mode is not `shared`
- rejects `continuity_mode` when mode is not `shared`
Dashboard accounts context editing:
- `PUT /api/accounts/:name/context` updates context mode/group/continuity for existing auth accounts
- rejects CLIProxy OAuth account keys for this route
- applies normalization/validation rules above
Shared resource editing:
- `PUT /api/accounts/:name/shared-resources` updates `shared_resource_mode` for existing auth accounts
- accepts only `shared` or `profile-local`
- rejects CLIProxy OAuth account keys for this route
- reconciles the account instance after metadata is updated
- Dashboard -> Accounts exposes this as a separate Resources action so it is not confused with History Sync.
- Dashboard -> Shared Resources shows the shared hub inventory for commands, skills, agents, plugins, and `settings.json`.
- The Plugins tab is registry-oriented: installed plugin entries come from `installed_plugins.json`, while internal cache/data/marketplace folders stay hidden unless a real plugin entry exists.
- Shared `settings.json` is read-only in the Shared Resources page and still edited through the settings surfaces that own those values.
## Commands
### `ccs config auth setup`
Interactive wizard to configure dashboard login.
```bash
$ ccs config auth setup
╭─────────────────────────────────╮
│ Dashboard Auth Setup │
╰─────────────────────────────────╯
[i] Configure username and password for dashboard access.
Password will be hashed with bcrypt before storage.
Username
Enter username: admin
Password
Minimum 8 characters
Enter password: ********
Confirm password: ********
[i] Hashing password...
[OK] Dashboard authentication configured
[i] Settings saved to ~/.ccs/config.yaml
[i] Username: admin
[i] Session timeout: 24 hours
Start dashboard: ccs config
Show status: ccs config auth show
Disable auth: ccs config auth disable
```
### `ccs config auth show`
Display current authentication status.
```bash
$ ccs config auth show
╭─────────────────────────────────╮
│ Dashboard Auth Status │
╰─────────────────────────────────╯
Configuration
[OK] Authentication: Enabled
[OK] Username: admin
[i] Session timeout: 24 hours
Commands
ccs config auth setup Configure authentication
ccs config auth disable Disable authentication
ccs config Open dashboard
```
### `ccs config auth disable`
Disable dashboard authentication with confirmation.
```bash
$ ccs config auth disable
╭─────────────────────────────────╮
│ Disable Dashboard Auth │
╰─────────────────────────────────╯
[!] This will disable login protection for the dashboard.
[i] Anyone with network access will be able to view the dashboard.
Disable authentication? [y/N]: y
[OK] Dashboard authentication disabled
[i] Credentials preserved - re-enable with: ccs config auth setup
```
### `ccs config auth --help`
Display usage information.
## Environment Variables
Environment variables override `config.yaml` values:
| Variable | Description |
|----------|-------------|
| `CCS_DASHBOARD_AUTH_ENABLED` | Enable/disable auth (`true`/`false`) |
| `CCS_DASHBOARD_USERNAME` | Username |
| `CCS_DASHBOARD_PASSWORD_HASH` | Bcrypt password hash |
### Generating a Password Hash
Use bcrypt to generate a hash:
```bash
# Using Node.js
node -e "console.log(require('bcrypt').hashSync('your-password', 10))"
# Using npx
npx bcrypt-cli hash "your-password"
```
## Configuration
Settings are stored in `~/.ccs/config.yaml`:
```yaml
# Dashboard Auth: Optional login protection for CCS dashboard
# Generate password hash: npx bcrypt-cli hash "your-password"
# ENV override: CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, CCS_DASHBOARD_PASSWORD_HASH
dashboard_auth:
enabled: true
username: "admin"
password_hash: "$2b$10$..."
session_timeout_hours: 24
```
## Security Notes
1. **Bcrypt hashing**: Passwords are hashed with bcrypt (10 rounds) before storage
2. **Session cookies**: Sessions use HTTP-only cookies (not accessible via JavaScript)
3. **Rate limiting**: Login attempts are rate-limited (5 per 15 minutes)
4. **Fail-closed remote writes**: When auth is disabled, sensitive management routes allow localhost only
5. **File permissions**: Config file is created with 0o600 permissions
## Troubleshooting
### "Authentication not configured"
Run `ccs config auth setup` to configure credentials.
If you are using the integrated Docker stack, run that command inside `ccs-cliproxy`. Running it on the outer host shell updates a different config directory and will not unlock the running dashboard.
### Forgot password
Run `ccs config auth setup` again to set a new password.
### ENV override not working
Ensure the variable is exported:
```bash
export CCS_DASHBOARD_AUTH_ENABLED=true
export CCS_DASHBOARD_USERNAME=admin
export CCS_DASHBOARD_PASSWORD_HASH='$2b$10$...'
```
### Session expired immediately
Check `session_timeout_hours` in config. Default is 24 hours.
### "Invalid ... context_group ..."
This error comes from `PUT /api/config` when an account explicitly sets shared mode with an invalid group. Use a canonical group value (for example: `team-alpha`).
## See Also
- [Dashboard Auth Feature](https://ccs.kaitran.ca/features/dashboard-auth) - Full documentation
- [Config Schema](https://ccs.kaitran.ca/reference/config-schema) - All config options
docs/session-sharing-technical-analysis.md
-216
View File
@@ -1,216 +0,0 @@
# Session Sharing Technical Analysis
Last Updated: 2026-05-05
## Summary
CCS supports practical cross-account continuity by sharing workspace context files between selected accounts, while keeping credentials isolated per account.
This is implemented as a context policy per account:
- `isolated` (default): account keeps its own workspace context
- `shared` + `standard` (default): account workspace context is linked to a shared context group
- `shared` + `deeper` (advanced opt-in): account also shares continuity artifacts
## Recommended Two-Account Route
Use `ccs auth` account profiles when you want two real Claude accounts and want to choose which one runs each session:
```bash
ccs auth create work
ccs auth create personal
ccs work
ccs personal
```
This keeps usage and credentials isolated. Each account owns its own Claude config directory, login state, and `.anthropic` credentials.
Shared Resources are separate from History Sync. By default, non-bare account profiles inherit Claude-local resources from native Claude:
```text
~/.ccs/instances/<account>/settings.json
-> ~/.ccs/shared/settings.json
-> ~/.claude/settings.json
```
This covers ordinary Claude Code `settings.json`, commands, skills, agents, and plugins. It is not token sharing. `ccs auth show <account>` reports `Resources`, `Settings`, `History`, and `Plain ccs` lanes so users can see whether shared resources and resume history are aligned.
For existing accounts, change Shared Resources from the CLI:
```bash
ccs auth resources work --mode profile-local
ccs auth resources work --mode shared
```
- `shared`: link plugins, commands, skills, agents, and `settings.json` from the shared Claude resource layout.
- `profile-local`: detach those shared resources for the account. This is the existing `--bare` behavior exposed as an existing-account setting.
Only opt in to shared history when both accounts should see the same local continuity:
```bash
ccs auth create work2 --share-context --context-group daily --deeper-continuity
```
For existing History Sync, use Dashboard -> Accounts -> Sync on both accounts, set both to `shared`, and use the same `History Sync Group`. Use `deeper` only when users expect stronger local handoff beyond project context. History Sync does not control plugins or `settings.json`; use `ccs auth resources` for that.
## Why This Is Safe Enough
CCS only shares workspace context paths (project/session context files). It does **not** merge or copy authentication credentials between accounts.
Credential storage remains per account instance.
## Implementation Model
Account metadata is stored in `~/.ccs/config.yaml`:
```yaml
accounts:
work:
created: "2026-02-24T00:00:00.000Z"
last_used: null
shared_resource_mode: "shared"
context_mode: "shared"
context_group: "team-alpha"
continuity_mode: "deeper"
```
Rules:
- `shared_resource_mode` controls commands, skills, agents, plugins, and `settings.json` (`shared` or `profile-local`)
- `context_mode` must be `isolated` or `shared`
- `context_group` is required when `context_mode=shared`
- `continuity_mode` is valid only when `context_mode=shared` (`standard` or `deeper`)
- group normalization: trim, lowercase, internal spaces -> `-`
- group must start with a letter and only include `[a-zA-Z0-9_-]`
- max length: `64`
Deeper continuity links these directories per context group:
- `session-env`
- `file-history`
- `shell-snapshots`
- `todos`
`.anthropic` and account credentials remain isolated.
## Cross-Profile Inheritance (API / CLIProxy / Copilot)
You can explicitly map non-account profiles (including `default`) to reuse continuity artifacts from an account profile:
```yaml
continuity:
inherit_from_account:
glm: pro
gemini: pro
copilot: pro
```
Behavior:
- Applies only when running Claude target (`ccs <profile>` or `--target claude`)
- Does not change provider credentials or API routing
- Reuses `CLAUDE_CONFIG_DIR` from mapped account profile after normal account context policy resolution
- Invalid/missing mapped accounts are skipped safely
### Resume Lane Note
Resume follows the active `CLAUDE_CONFIG_DIR`, not just the continuity group:
- plain `ccs -r` resumes the lane plain `ccs` is using right now
- `ccs <account> -r` resumes only that account lane
- those two commands can point at different continuity inventories
That means `shared + deeper` on an account does **not** automatically make old plain-`ccs` resume history appear inside `ccs <account> -r`.
If you want future plain `ccs` sessions to use an account lane, either:
```bash
ccs auth default work
```
or map the default profile explicitly:
```yaml
continuity:
inherit_from_account:
default: work
```
Example with an existing `ck` account:
```bash
ccs auth show ck
ccs auth backup default
ccs auth default ck
```
`ccs auth default ck` makes future plain `ccs` sessions use the `ck` account lane, so future `ccs` and `ccs ck` resume from the same local inventory. It does not automatically import old native `~/.claude/projects` history into `ck`; keep using `ccs -r` for the old native lane until you intentionally migrate that local history.
## User Workflows
### New account with shared context
```bash
ccs auth create work2 --share-context
ccs auth create backup --share-context --context-group sprint-a
ccs auth create backup2 --share-context --context-group sprint-a --deeper-continuity
```
### Existing account
History Sync:
- Open `ccs config`
- Go to `Accounts`
- Click the pencil icon (`Edit History Sync`)
- Choose `isolated` or `shared`, set group, and (optionally) choose deeper continuity
Shared Resources:
```bash
ccs auth resources work --mode profile-local
ccs auth resources work --mode shared
```
Dashboard:
- Open `ccs config`
- Go to `Accounts`
- Use `Resources` to switch an existing account between `shared` and `profile-local`
- Go to `Shared Resources` to inspect the shared commands, skills, agents, plugins, and `settings.json` hub
No account recreation required for this workflow.
### Backup Before Changing Sync
CCS can back up local continuity artifacts before you change settings:
```bash
ccs auth backup work
ccs auth backup default
```
- `ccs auth backup work` backs up the selected account lane
- `ccs auth backup default` backs up the lane plain `ccs` would use right now
- this is a local continuity backup, not a guaranteed export of all upstream Claude-hosted resume state
## Current Limitations
- Shared context is local filesystem sharing. It does not bypass remote provider permission models.
- Session continuity still depends on what the upstream tool/provider stores and allows.
- Context sharing should only be enabled for accounts you intentionally trust to share workspace history.
- Shared Resources inspection is read-only in the dashboard. Editing individual files still belongs to the owning command, skill, plugin, or settings surface.
## Alternative: CLIProxy Claude Pool
For users who prefer lower manual account switching, use CLIProxy Claude pool instead:
- Authenticate pool accounts via `ccs cliproxy auth claude`
- Manage account pool behavior in `ccs config` -> `CLIProxy Plus`
## Validation Checklist
- Confirm account row shows `shared (<group>)` in Dashboard Accounts table
- Switch between accounts in the same group and verify workspace continuity
- Run `ccs doctor` if symlink/context health looks inconsistent