ocs 0.1.5

A session picker for OpenCode
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162

## ocs

[![release](https://img.shields.io/github/release/terror/ocs.svg?label=release&style=flat&labelColor=1d1d1d&color=424242&logo=github&logoColor=white)](https://github.com/terror/ocs/releases/latest)
[![build](https://img.shields.io/github/actions/workflow/status/terror/ocs/ci.yaml?branch=master&style=flat&labelColor=1d1d1d&color=424242&logo=GitHub%20Actions&logoColor=white&label=build)](https://github.com/terror/ocs/actions/workflows/ci.yaml)
[![codecov](https://img.shields.io/codecov/c/gh/terror/ocs?style=flat&labelColor=1d1d1d&color=424242&logo=Codecov&logoColor=white)](https://codecov.io/gh/terror/ocs)
[![downloads](https://img.shields.io/github/downloads/terror/ocs/total.svg?style=flat&labelColor=1d1d1d&color=424242&logo=github&logoColor=white)](https://github.com/terror/ocs/releases)

`ocs` is a better session picker for [opencode](https://opencode.ai/).

<img width="1667" alt="ocs" src="screenshot.png" />

`ocs` indexes your local OpenCode sessions and presents them in a full-screen
fuzzy finder. Search by title, project directory, session ID, or text from the
four most recent user prompts. The selected session is reopened with
`opencode --session` in its original directory when that directory still
exists.

Each row shows when the session was updated, its model, cost, and total token
usage.

By default, `ocs` shows only sessions started in the current directory.

The preview shows the session title, directory, ID, and complete text-message
transcript. Press control-d to delete the selected session and its messages.

## Installation

`ocs` should run on any system, including Linux, MacOS, and Windows.

The easiest way to install it is by using
[cargo](https://doc.rust-lang.org/cargo/), the Rust package manager:

```bash
cargo install ocs
```

Otherwise, see below for the complete package list:

#### Cross-platform

<table>
  <thead>
    <tr>
      <th>Package Manager</th>
      <th>Package</th>
      <th>Command</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td><a href=https://www.rust-lang.org>Cargo</a></td>
      <td><a href=https://crates.io/crates/ocs>ocs</a></td>
      <td><code>cargo install ocs</code></td>
    </tr>
    <tr>
      <td><a href=https://brew.sh>Homebrew</a></td>
      <td><a href=https://github.com/terror/homebrew-tap>terror/tap/ocs</a></td>
      <td><code>brew install terror/tap/ocs</code></td>
    </tr>
  </tbody>
</table>

### Pre-built binaries

Pre-built binaries for Linux, MacOS, and Windows can be found on
[the releases page](https://github.com/terror/ocs/releases).

## Usage

Run `ocs` without arguments to browse sessions. Type to fuzzy-search, use the
arrow keys to move through matches, press enter to open the selected session,
or press control-d to delete it. Press escape or control-c to cancel.

```bash
ocs
```

Pass an initial query with `--query`:

```bash
ocs --query picker
```

Use `--all` to show sessions from every directory:

```bash
ocs --all
```

Use `--print` to write the selected session ID to standard output instead of
opening OpenCode. This is useful for scripts and shell integrations:

```bash
ocs --print
```

### Shell Integration

Add the appropriate command to your shell configuration to bind `control-x`
followed by `s` to session history search.

Bash (`.bashrc`):

```bash
eval "$(ocs init bash)"
```

Zsh (`.zshrc`):

```zsh
eval "$(ocs init zsh)"
```

The current command line is used as the initial search query. Selecting a
session clears the command line and opens the session immediately. The
integration also defines an `ocs` function that passes the selected session ID
to OpenCode. Arguments are forwarded to the `ocs` binary, so commands such as
`ocs --query picker` continue to work.

## Configuration

On first run, `ocs` creates `config.toml` in the platform configuration
directory selected by `confy`. On Linux and macOS this is normally
`$XDG_CONFIG_HOME/ocs/config.toml`, or `~/.config/ocs/config.toml` when
`XDG_CONFIG_HOME` is unset.

Set `opencode_args` to pass additional arguments whenever a session is opened:

```toml
opencode_args = ["--auto"]
```

Each array entry is passed to OpenCode as one argument. These arguments do not
affect database discovery or session deletion commands.

## Database

By default, `ocs` discovers the active OpenCode database by running
`opencode db path`, which honors the `OPENCODE_DB` environment variable and
the per-channel database files used by beta and dev installs. When OpenCode
is not installed, `ocs` falls back to `opencode.db` in
`$XDG_DATA_HOME/opencode`, or `$HOME/.local/share/opencode` when
`XDG_DATA_HOME` is unset.

Pass `--database` to use a specific OpenCode database file, such as a
separate profile or a copied database:

```bash
ocs --database /path/to/opencode.db
```

Pass `--data-dir` to use an alternate OpenCode data directory, as before:

```bash
ocs --data-dir /path/to/opencode
```

## Prior Art

This project was inspired by the session picker built into
[opencode](https://opencode.ai/). `ocs` makes old sessions easier to find by
searching their metadata and recent prompts, with a full transcript preview.