acpx

[00:00] ACPX is a library or a tool from the folks at OpenClaw that allows you to talk to agents from the command line. That means without loading up the actual coding agent, you can communicate with it. And more importantly, at least for me personally, is allows you to talk to your coding agent from code. Let’s get right into it. So to install ACPX globally, we’re going to do npm installed tack G ACPX at latest. And we’re going to confirm we have it with ACPX version. Cool.

[00:33] That’s there. Now we’re going to run ACPX codex and we’re going to say what is in this repo? And it’s not going to work. It’s going to say we need to create a session. So let’s do that. We’ll paste that in there. And now we’ve got a session. So we try that command again and we can see something’s happening. We’re getting a lot of garbage, but there it is. There’s all of our, this is what’s in the repo. Great.

[00:54] And now if we want to close the session, we say ACPX codex or our agent sessions close. Cool. So that’s done. We can also do a name session. So on this one, I’m going to use pi. I’m going to say sessions new. I’m going to give it a name of docs. So now I can use that session for anything docs related. So here I’m going to say ACPX pi tack s for the session docs. And I’m going to say create me or read me. They list the dependencies for this project. We’ll let that run. We’ll jump over to our editor and here’s our read me. It looks great.

[01:31] Now, if we want to run an agent without a session, we can use exec. So I’ll say ACPX open code, exec. And then I just pass in my prompt. And in this case, I’m going to pass in this prompt. It says fetch the top 10 repositories from this website and save them as a Jason file. We’ll check that out in the repo. And there we go. We have our Jason generated without creating a session. So another really cool thing about ACPX is we can use it as a TypeScript library, which means we can write code that executes these commands without working in our terminal. There’s an experimental feature called flows that we’re going to take a look at now that I’m super excited about.

[02:05] So to install it as a library, we’re going to do MPM install ACPX. I’ll do at latest and we’ll check out our package Jason and there it is. Cool. So I’m going to create a new file here. I’m going to call it repo.flow.ts. And into that, we’re going to bring in a few things from ACPX and I’ve got this little Jason DB for looking at a repos Jason to get us started. We’re going to see export default define flow. And this guy is going to have a name. I’ll just call it flow for now. It’s going to have a start at, and we’ll talk about this in a moment, but I’m going to say the start at is task. And that’s going to have a list of nodes and an object. And it’s also going to have a list of edges. So very much like a graph.

[02:59] So let’s create our first node. I’m going to call this task, which is the node that it’s going to start at. And this one’s going to be a compute node, which means it’s not using any of the agent stuff. It’s just a function. So I’m going to have async function called run. And into that, I’m going to get my tasks and say task equals await. And I’m going to use this little Jason DB guy I got. So I’m going to say find open task from repos Jason. And now we’re just going to wait setting progress on that guy. So I’m going to set the progress from zero to one on this task in the repos dot Jason. And then I’m just going to return the task. So that’s the result of the first node in our flow.

[03:46] So for our second node, I’m going to say fetch. And this one is actually going to use an agent. So I’m going to use ACP, which we pulled in from the ACP flows library, and I’m going to give it a prompt. And in the prompt, I have a function that takes in an outputs and that’s whatever came from the previous node. And then I’m just going to get my task from the outputs. And here I’m just going to return my prompts. And my prompt is use the URL you got in the Jason in order to find the read me and then save that locally as a markdown file.

[04:08] So let’s jump down here to edges where we’re going to create our edges and each one’s going to have a from and a to just like any graph. And this one’s going to be from task to fetch. I’m going to add one more edge in here and it’s going to be from fetch to done. And we’ll go ahead and create a very quick node done. I’m just going to paste this in. It’s a compute. It does a done true and a message.

[04:39] Okay. This all looks pretty good. So let’s go ahead and try to run this guy. Now on the right, I’ve got a watch on my repos, Jason, that’ll update every half second. And on the left, I’m going to say ACPX flow run our flow file default agent. And I’m going to go ahead and use open code again. So we’ll run that. And you can see on the right, it already updated the formatting at least. And that status is set to one. It was previously zero.

[05:07] So it says it’s finished. Let’s go take a look and a repo. And if I go to this output directory, sure enough, we have our read me from the first repo in the list and our status has been updated. Awesome. So let me go ahead and close some of these documents out.

[05:24] And back here in our repo flow, what I’m going to do is I’m just going to drop in some new notes. So after fetch, we’re going to have fetched, which is going to use our set progress to update the task status to two that we’re going to have summarize. And this guy is going to create a briefing from the markdown that we saved of the readme. Summarize is going to go to summarized. We’re going to update the status to three. And we’re going to come down here to our edges. And let’s see, from fetch, we’re going to go to fetched. And from fetched, we’re going to go to summarize. And from summarize, we’re going to go to summarized. And from summarized, we’re going to go to done. So now we’ve got a much more complex flow. Let’s try to run this guy. So we can see our status is currently one. And we’re going to wait for that to go from one to two to three. It says it’s done. Let’s check it out. Cool.

[06:18] So we got our number two repository readme, and we’ve got our brief with the headings that I mentioned in the prompt.

[06:45] But we do have a problem here. This guy, I have to run it for each and every task every time. So what we’re going to do is first thing, we’re going to clear all this stuff out. So I’m getting rid of all the markdowns and the one brief that we have. And I’m going to go to the repos, Jason, and I’m going to set all these guys back to zero. We’re going to come in here to our task node. And I’m simply going to say, if we don’t have a task, return this new object with a key of next done. And then on our regular return, I’m going to say next is fetch, and then just spread the task in there. And then we’ll come down to our edge and I’m going to forward summarize to task. And now task is going to go to a switch command. So there’s no two. I’m going to say on dollar dot next, which is the convention for accessing when one of those fields has been updated. And I’m going to create my cases. So the first one is going to be fetch. If we got fetch, go to the fetch node. If we got done, go to the done node. And now theoretically, this guy should loop over every single task in our Jason.

[07:52] So on the right, we can see all the zeros and we’re going to run our command and we’re going to keep an eye on our Jason. We can already see that first one went to one as soon as I ran this. So we can see all of the tasks being completed, each one going from one to three. So let’s take a look. Awesome. We’ve got all of our read means. We’ve got all of our tasks with a status of three. We’ve got all of our briefs.

[08:37] So this was a pretty contrived example of how to use ACPX in your code. There’s a bunch more examples in their repository. This is a really powerful tool as a building block for creating much larger, much more complex applications.