Expose Session Context To Child Processes
Hey guys! Have you ever found yourself in a situation where you're running multiple opencode sessions and it's a real pain to keep track of which session is doing what? I'm talking about those iterative workflows, like when you're using Ralph loops, and you're just drowning in logs and metrics. Well, I've got a solution that's going to make your life a whole lot easier. Let's dive into how we can expose session context to child processes using environment variables. This enhancement ensures that user scripts and tools executed via opencode can easily identify which opencode session they're running in, streamlining the correlation of logs, metrics, and outputs across multiple sessions.
The Problem: Identifying Opencode Sessions
So, here's the deal. When you're running scripts and tools through opencode, especially using bash or shell commands, these processes often operate in isolation. This isolation means they have no clue which opencode session they're actually running under. Imagine you're knee-deep in a Ralph loop, firing off new opencode sessions with each iteration. Without a way to identify each session, correlating logs, metrics, and outputs becomes a total nightmare. You're basically flying blind, trying to piece together what happened where and when. This is not ideal, especially when you're trying to debug or optimize your workflows. The core issue is the lack of session metadata available to child processes spawned by opencode. This missing context makes it incredibly difficult to track and manage concurrent or sequential opencode sessions effectively. Think about it: you're running a script that's supposed to fix a bug, but you can't easily tell which session the script ran in. That's a huge problem! We need a way to provide this context, so let's look at a use case to make this crystal clear.
Use Case: Ralph Loops and Session Logging
Let's say you're running a Ralph loop—a common scenario for many of us. Each iteration of this loop spawns a new opencode session. Now, you need to log which session each iteration corresponds to. Why? Because you want to track the progress, identify bottlenecks, or debug issues that might arise during the loop. The problem is, the child processes spawned by opencode have absolutely no access to session metadata. They're like little orphans, unaware of their parentage. This lack of awareness means you can't easily correlate the logs from each iteration with the specific session that ran it. You end up with a jumbled mess of logs, and you're left scratching your head, trying to figure out what went wrong where. For example, imagine an error occurs in one of the iterations. Without session context, you'd have to manually sift through all the logs to find the relevant information. That's a massive time sink and a major source of frustration. What we really need is a way for these child processes to know which session they belong to, so we can easily track and correlate their activities. This is where exposing session context via environment variables comes to the rescue. By providing this context, we can enable proper tracking and correlation of work across multiple concurrent or sequential opencode sessions, making our lives as developers and engineers so much easier. It’s about making the system work for us, not against us!
The Solution: Environment Variables to the Rescue
Alright, so how do we solve this mess? The answer is surprisingly simple: we expose session context to child processes via environment variables. What are environment variables, you ask? They're basically named values that can be accessed by processes running on your system. We're going to set two key environment variables: OPENCODE_SESSION_ID and OPENCODE_SESSION_TITLE. The OPENCODE_SESSION_ID will hold the unique identifier of the current session (think something like ses_xyz123), and the OPENCODE_SESSION_TITLE will contain the human-readable title of the session (e.g., "Fix bug in auth flow"). These variables will be set in two important user-facing command execution contexts:
- Bash tool: When you execute commands via the bash tool, these variables will be automatically set for you.
- Prompt shell: When you're running commands directly in the shell, these variables will also be available.
This means that no matter how you're interacting with opencode, you'll have access to the session context. This is a game-changer because it allows your scripts and tools to easily identify which session they're running in. The beauty of this approach is its simplicity and flexibility. You don't need to modify your existing scripts or tools to take advantage of this feature. Just access the environment variables, and you're good to go. For example, you can easily log the session ID and title to a file, include them in your metrics, or use them to filter your logs. This simple addition can have a huge impact on your ability to track and manage your opencode sessions effectively. Let's dig into the implementation details to understand how this all works behind the scenes.
Implementation Details: Dynamic Setting and Error Handling
Now, let's get into the nitty-gritty of how this is implemented. It's crucial to understand that these environment variables are set dynamically per spawn. What does that mean? Unlike other environment variables like AGENT and OPENCODE, which are set globally at startup, OPENCODE_SESSION_ID and OPENCODE_SESSION_TITLE are set each time a new process is spawned. Why is this important? Because you can switch between sessions during interactive work. If these variables were set globally, they wouldn't reflect the current session you're working in. Dynamic setting ensures that the environment variables always reflect the correct session context, no matter how many times you switch between sessions. This requires a bit more work under the hood, but it's essential for providing accurate and reliable session context. Another important aspect of the implementation is session lookup and graceful error handling. We want to make sure that this new feature doesn't break any existing tests or mock contexts. To achieve this, we've implemented robust error handling that gracefully handles cases where the session context is not available. This could happen, for example, in older versions of opencode or in test environments where the session context is not properly set up. In these cases, the environment variables might be empty or contain default values, but the scripts and tools will continue to run without crashing. This ensures that we can introduce this new feature without disrupting existing workflows. It's all about providing a smooth and seamless experience for our users. To illustrate how this all works in practice, let's look at an example of how you can use these environment variables in your scripts.
Example Usage: Tracking Sessions in User Scripts
Okay, let's see how this works in practice. Imagine you have a simple bash script that you want to use to track which opencode session it's running in. Here's how you can do it:
#!/bin/bash
# User script can now access session context
echo "Running in session: $OPENCODE_SESSION_TITLE ($OPENCODE_SESSION_ID)" >> /var/log/opencode-iterations.log
In this script, we're simply accessing the OPENCODE_SESSION_TITLE and OPENCODE_SESSION_ID environment variables and writing them to a log file. This allows you to easily track which session each iteration of your Ralph loop corresponds to. You can then use this log file to analyze the performance of your different sessions, identify errors, or simply keep track of your work. This is just a simple example, but you can use these environment variables in many different ways. You can include them in your metrics, use them to filter your logs, or even use them to dynamically configure your scripts based on the session context. The possibilities are endless. The key takeaway here is that this new feature enables proper tracking and correlation of work across multiple concurrent or sequential opencode sessions. This can save you a ton of time and effort, and it can help you to be more productive and efficient. So, there you have it! By exposing session context to child processes via environment variables, we've made it much easier to track and manage your opencode sessions. This simple but powerful feature can help you to be more productive, efficient, and less frustrated. Go forth and conquer your opencode sessions, my friends!