Skip to content

Commit 3fa04f0

Browse files
AnnatarHeAnnatarHe
authored
Merge pull request #262 from shelltime/codex/update-readme-and-agents
[codex] refresh README and AGENTS docs
2 parents 2231cf6 + 4072a5b commit 3fa04f0

2 files changed

Lines changed: 175 additions & 83 deletions

File tree

‎AGENTS.md‎

Lines changed: 56 additions & 30 deletions
Original file line numberDiff line numberDiff line change
@@ -1,44 +1,70 @@
11
# Repository Guidelines
22

3-
## Project Structure & Module Organization
3+
## Project Identity
4+
This repo is the ShellTime CLI and daemon. Public-facing docs, command examples, and product references should use `ShellTime` and `shelltime.xyz`.
5+
6+
Code and imports currently use the module path `github.com/malamtime/cli`. Do not "fix" ShellTime branding in docs just because the module path says `malamtime`; the mismatch is intentional in the current repo state.
7+
8+
## Project Structure & Package Boundaries
49
This is a Go monorepo for the ShellTime CLI and daemon.
5-
- `cmd/cli/main.go`: CLI entrypoint (`shelltime`)
6-
- `cmd/daemon/main.go`: daemon entrypoint (`shelltime-daemon`)
7-
- `commands/`: CLI command implementations (for example `sync.go`, `doctor.go`, `daemon.install.go`)
8-
- `daemon/`: background services, socket handling, sync processors, OTEL handlers
9-
- `model/`: core domain logic (config, API clients, crypto, shell integrations)
10-
- `docs/`: user-facing docs (`CONFIG.md`, `CC_STATUSLINE.md`)
11-
- `fixtures/`: test fixtures
1210

13-
Keep new code in the existing package boundary; avoid mixing CLI wiring, daemon internals, and model logic.
11+
- `cmd/cli/main.go`: CLI entrypoint for `shelltime`
12+
- `cmd/daemon/main.go`: daemon entrypoint for `shelltime-daemon`
13+
- `commands/`: CLI command definitions and user-facing command behavior
14+
- `daemon/`: background services, socket handling, processors, and OTEL handlers
15+
- `model/`: config, API clients, shell integrations, crypto, and shared domain logic
16+
- `docs/`: user-facing docs such as `CONFIG.md` and `CC_STATUSLINE.md`
17+
- `fixtures/`: reusable test fixtures
18+
19+
Keep new code inside the existing package boundary. Do not mix CLI wiring, daemon internals, and model logic in the same package.
1420

1521
## Build, Test, and Development Commands
22+
1623
- `go build -o shelltime ./cmd/cli/main.go`: build the CLI binary
1724
- `go build -o shelltime-daemon ./cmd/daemon/main.go`: build the daemon binary
18-
- `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...`: run full test suite with coverage (matches CI)
19-
- `go test ./commands/...` (or `./daemon/...`, `./model/...`): package-level tests
20-
- `go test -run TestName ./daemon/`: run a single test
21-
- `go fmt ./... && go vet ./...`: format and static checks
22-
- `mockery`: regenerate mocks (configured by `.mockery.yml`)
23-
- `pp g`: regenerate PromptPal-generated types before tests/releases
25+
- `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...`: run the full suite with coverage
26+
- `go test ./commands/...`: run command-package tests
27+
- `go test ./daemon/...`: run daemon-package tests
28+
- `go test ./model/...`: run model-package tests
29+
- `go test -run TestName ./daemon/`: run a targeted daemon test
30+
- `go fmt ./...`: format Go code
31+
- `go vet ./...`: run static analysis
32+
- `mockery`: regenerate mocks when interfaces change
33+
- `pp g`: regenerate PromptPal-generated artifacts when relevant
34+
35+
Use Go 1.26, as declared in `go.mod`.
2436

2537
## Coding Style & Naming Conventions
26-
Use standard Go conventions and keep code `gofmt`-clean (tabs, canonical spacing/import grouping).
27-
- File naming: lowercase with underscores or dotted qualifiers (for example `daemon.install.go`, `api.base.go`)
28-
- Tests: `*_test.go` files with clear `TestXxx` names
29-
- Commits and scopes should reflect touched package areas (`commands`, `daemon`, `model`, `docs`)
38+
Use standard Go conventions and keep code `gofmt`-clean.
3039

31-
## Testing Guidelines
32-
Testing uses Go `testing` plus `testify`.
40+
- File naming: lowercase with underscores or dotted qualifiers such as `daemon.install.go` or `api.base.go`
41+
- Tests: `*_test.go` with clear `TestXxx` names
3342
- Prefer table-driven tests for pure logic
34-
- Use suite-based tests (`suite.Suite`, `SetupTest`, `TearDownTest`) for stateful daemon flows
35-
- Keep fixtures in `fixtures/` when payloads are reused
36-
- Ensure `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...` passes before opening PRs
43+
- Use `testify` suites for stateful daemon flows
44+
- Keep comments brief and only where they reduce real ambiguity
45+
46+
## Testing Guidance
47+
48+
- Put reusable payloads and fixtures under `fixtures/`
49+
- Prefer package-level test runs while iterating, then run the full suite before finishing
50+
- Ensure `go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...` passes before opening a PR or cutting a release
51+
52+
## Documentation Maintenance
53+
When command behavior, setup flow, config formats, or integrations change, update the docs in the same change.
54+
55+
- `README.md`: concise user-facing overview, install/setup flow, current command surface, and links
56+
- `docs/CONFIG.md`: detailed config semantics, file locations, defaults, and OTEL settings
57+
- `docs/CC_STATUSLINE.md`: Claude Code statusline behavior, formatting, and platform notes
58+
- `AGENTS.md`: contributor and agent workflow guidance for this repo
59+
60+
Do not leave `README.md` advertising commands that no longer exist, and do not document new commands only in code.
3761

3862
## Commit & Pull Request Guidelines
39-
History follows Conventional Commits with scope, e.g. `fix(daemon): ...`, `feat(commands): ...`, `refactor(model): ...`.
40-
- Write focused commits with one behavioral change each
41-
- PRs should include: concise summary, why the change is needed, and test evidence
42-
- Link related issues when applicable
43-
- If behavior/output changes, include CLI examples or screenshots
44-
- Regenerate artifacts (`pp g`, `mockery`) when relevant so CI stays green
63+
History follows Conventional Commits with scope, for example:
64+
65+
- `fix(daemon): ...`
66+
- `feat(commands): ...`
67+
- `refactor(model): ...`
68+
- `docs(readme): ...`
69+
70+
Keep commits focused on one behavioral change. PRs should include a short summary, why the change is needed, and test evidence. Link related issues when applicable. If behavior or output changes, include CLI examples or screenshots. Regenerate artifacts such as `pp g` and `mockery` when needed so CI remains green.

‎README.md‎

Lines changed: 119 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -3,78 +3,140 @@
33
[![codecov](https://codecov.io/gh/shelltime/cli/graph/badge.svg?token=N09WIJHNI2)](https://codecov.io/gh/shelltime/cli)
44
[![shelltime](https://api.shelltime.xyz/badge/AnnatarHe/count)](https://shelltime.xyz/users/AnnatarHe)
55

6-
Track and analyze your DevOps workflow. [shelltime.xyz](https://shelltime.xyz)
6+
ShellTime is a CLI and background daemon for tracking shell activity, syncing command history, and wiring AI coding tools into a shared telemetry stream. The public product and hosted service are ShellTime at [shelltime.xyz](https://shelltime.xyz).
7+
8+
The Go module path is `github.com/malamtime/cli`. That naming mismatch is intentional in this repo today; use `ShellTime` for product-facing docs and `github.com/malamtime/cli` for imports and module references.
79

810
## Install
911

1012
```bash
1113
curl -sSL https://shelltime.xyz/i | bash
1214
```
1315

14-
## Setup
16+
## Quick Start
17+
18+
The fastest setup path is:
1519

1620
```bash
17-
shelltime init # Authenticate
18-
shelltime hooks install # Enable automatic tracking
19-
shelltime daemon install # Optional: background sync for <8ms latency
21+
shelltime init
2022
```
2123

22-
## Commands
24+
`shelltime init` authenticates the CLI, installs shell hooks, installs the daemon, and attempts to configure Claude Code and Codex OTEL integration.
25+
26+
If you prefer the manual flow:
27+
28+
```bash
29+
shelltime auth
30+
shelltime hooks install
31+
shelltime daemon install
32+
shelltime cc install
33+
shelltime codex install
34+
```
35+
36+
## What ShellTime Does
37+
38+
- Tracks shell commands locally with masking and exclusion support.
39+
- Syncs command history to ShellTime for search and analysis.
40+
- Runs a background daemon for low-latency, non-blocking sync.
41+
- Integrates with Claude Code and OpenAI Codex through OTEL forwarding.
42+
- Shows live Claude Code statusline data for cost, quota, time, and context.
43+
- Syncs supported dotfiles to and from the ShellTime service.
44+
45+
## Command Overview
46+
47+
### Core setup and auth
48+
49+
| Command | Description |
50+
|---------|-------------|
51+
| `shelltime init` | Bootstrap auth, hooks, daemon, and AI-code integrations |
52+
| `shelltime auth` | Authenticate with `shelltime.xyz` |
53+
| `shelltime doctor` | Check installation and environment health |
54+
| `shelltime web` | Open the ShellTime dashboard in a browser |
55+
56+
### Tracking and sync
57+
58+
| Command | Description |
59+
|---------|-------------|
60+
| `shelltime track` | Record a shell command event |
61+
| `shelltime sync` | Manually sync pending local data |
62+
| `shelltime ls` | List locally saved commands |
63+
| `shelltime gc` | Clean internal storage and logs |
64+
| `shelltime rg "pattern"` | Search synced command history |
65+
66+
### AI helpers and integrations
2367

2468
| Command | Description |
2569
|---------|-------------|
26-
| `shelltime sync` | Sync pending commands to server |
27-
| `shelltime rg "pattern"` | Search synced commands (alias: `grep`) |
28-
| `shelltime q "prompt"` | AI-powered command suggestions |
29-
| `shelltime doctor` | Diagnose installation issues |
30-
| `shelltime web` | Open dashboard in browser |
31-
| `shelltime gc` | Clean old tracking data |
32-
| `shelltime ls` | List pending commands |
70+
| `shelltime query "prompt"` | Ask AI for a suggested shell command |
71+
| `shelltime q "prompt"` | Alias for `shelltime query` |
72+
| `shelltime cc install` | Install Claude Code OTEL shell configuration |
73+
| `shelltime cc uninstall` | Remove Claude Code OTEL shell configuration |
74+
| `shelltime cc statusline` | Emit statusline JSON for Claude Code |
75+
| `shelltime codex install` | Add ShellTime OTEL config to `~/.codex/config.toml` |
76+
| `shelltime codex uninstall` | Remove ShellTime OTEL config from `~/.codex/config.toml` |
77+
78+
### Environment helpers
79+
80+
| Command | Description |
81+
|---------|-------------|
82+
| `shelltime hooks install` | Install shell hooks |
83+
| `shelltime hooks uninstall` | Remove shell hooks |
84+
| `shelltime daemon install` | Install the ShellTime daemon service |
85+
| `shelltime daemon status` | Check daemon status |
86+
| `shelltime daemon reinstall` | Reinstall the daemon service |
87+
| `shelltime daemon uninstall` | Remove the daemon service |
88+
| `shelltime alias import` | Import aliases from shell config files |
89+
| `shelltime config view` | Show the merged current configuration |
90+
| `shelltime schema` | Generate JSON schema for config autocompletion |
91+
| `shelltime ios dl` | Open the ShellTime iOS App Store page |
92+
93+
### Dotfiles
94+
95+
| Command | Description |
96+
|---------|-------------|
97+
| `shelltime dotfiles push` | Push supported dotfiles to the server |
98+
| `shelltime dotfiles pull` | Pull supported dotfiles to local config |
3399

34100
## Configuration
35101

36-
Config file: `~/.shelltime/config.yaml`
102+
ShellTime stores data under `~/.shelltime/`.
103+
104+
- Main config: `~/.shelltime/config.yaml`
105+
- Local overrides: `~/.shelltime/config.local.yaml`
106+
- Also supported: `config.yml`, `config.toml`, `config.local.yml`, `config.local.toml`
107+
- Generated schema: `~/.shelltime/config-schema.json`
108+
109+
Minimal example:
37110

38111
```yaml
39-
token: "your-token"
40-
flushCount: 10 # Commands before sync
41-
gcTime: 14 # Days to retain data
42-
dataMasking: true # Mask sensitive data
43-
encrypted: false # E2E encryption (requires daemon)
112+
token: "your-api-token"
113+
flushCount: 10
114+
gcTime: 14
115+
dataMasking: true
44116

45-
# Exclude patterns (regex)
46117
exclude:
47118
- ".*password.*"
48119
- "^export .*"
49-
50-
# AI permissions
51-
ai:
52-
agent:
53-
view: false # Read-only commands
54-
edit: false # File modifications
55-
delete: false # Destructive commands
56120
```
57121
58-
Local overrides: `~/.shelltime/config.local.yaml`
122+
For the full configuration surface, defaults, OTEL settings, and AI options, see [docs/CONFIG.md](docs/CONFIG.md).
59123
60-
**[Full Configuration Guide](docs/CONFIG.md)** - Detailed documentation for all options
124+
## Daemon Mode
61125
62-
## Why Daemon Mode?
126+
The daemon keeps tracking fast by buffering and syncing in the background.
63127
64128
| Mode | Latency | Network Blocking |
65129
|------|---------|------------------|
66130
| Direct | ~100ms+ | Yes |
67131
| Daemon | <8ms | No |
68132
69-
The daemon handles network sync in the background with automatic retry and buffering.
70-
71-
## Claude Code Statusline Integration
133+
Use daemon mode if you want lower shell latency, retry handling, and background processing for sync and OTEL events.
72134
73-
Display real-time cost and context usage in [Claude Code's status bar](https://code.claude.com/docs/en/statusline).
135+
## Claude Code Statusline
74136
75-
### Setup
137+
ShellTime can provide a live statusline for [Claude Code](https://code.claude.com/docs/en/statusline).
76138
77-
Add to your Claude Code settings (`~/.claude/settings.json`):
139+
Add this to `~/.claude/settings.json`:
78140

79141
```json
80142
{
@@ -85,33 +147,37 @@ Add to your Claude Code settings (`~/.claude/settings.json`):
85147
}
86148
```
87149

88-
The status line will display:
150+
Example output:
89151

90-
```
152+
```text
91153
🌿 main* | 🤖 Opus | 💰 $0.12 | 📊 $3.45 | 🚦 5h:23% 7d:12% | ⏱️ 5m30s | 📈 45%
92154
```
93155

94-
| Section | Description |
95-
|---------|-------------|
96-
| 🌿 Git Branch | Current branch name (`*` if dirty) |
97-
| 🤖 Model | Current model name |
98-
| 💰 Session | Current session cost (clickable link to session detail) |
99-
| 📊 Daily | Today's total cost (clickable link to coding agent page) |
100-
| 🚦 Quota | Anthropic API quota utilization (macOS only, clickable link to usage settings) |
101-
| ⏱️ Time | AI agent session duration (clickable link to user profile) |
102-
| 📈 Context | Context window usage % |
156+
For formatting details and platform notes, see [docs/CC_STATUSLINE.md](docs/CC_STATUSLINE.md).
103157

104-
For full details, see [Claude Code Statusline Guide](docs/CC_STATUSLINE.md).
158+
## Security and Privacy
105159

106-
## Security
160+
- Data masking can redact sensitive command content before upload.
161+
- Exclusion patterns let you skip matching commands entirely.
162+
- Optional end-to-end encryption is available for supported flows.
163+
- Local config overrides can keep sensitive values out of the primary config file.
107164

108-
- **Data Masking**: Sensitive info automatically redacted
109-
- **E2E Encryption**: Hybrid RSA/AES-GCM encryption (v0.1.12+)
110-
- **Exclusion Patterns**: Regex-based command filtering
165+
## Development
166+
167+
Common local commands:
168+
169+
```bash
170+
go build -o shelltime ./cmd/cli/main.go
171+
go build -o shelltime-daemon ./cmd/daemon/main.go
172+
go test -timeout 3m -coverprofile=coverage.txt -covermode=atomic ./...
173+
go fmt ./...
174+
go vet ./...
175+
```
111176

112177
## Links
113178

114-
- [Documentation](https://deepwiki.com/shelltime/cli)
179+
- [Configuration Guide](docs/CONFIG.md)
180+
- [Claude Code Statusline Guide](docs/CC_STATUSLINE.md)
115181
- [Dashboard](https://shelltime.xyz)
116182
- [Issues](https://github.com/shelltime/cli/issues)
117183

0 commit comments

Comments
 (0)